Stoory Hire Specialist

Searches for specialists in the Stoory marketplace via semantic search. Result quality depends mostly on a well-built `query` — see the `query` field description. If a result has <3 hits or only 'Alternative fit', retry with a simpler/broader query (see `query`) instead of asking the user; only after about 3 failed attempts tell the user you have no one to recommend for these requirements and suggest widening the criteria.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 120,
      "description": "The specialist's role and skills, MAX 12 words, natural language — not a full sentence describing the user's problem. In English if possible (faster response and better hits than other languages). Good: 'Senior Stripe developer', 'Professional logo designer', 'Experienced UX designer for mobile apps'. Bad: 'I need someone who can help me with branding and visual identity design' (full sentence instead of a role), 'Full-stack developer with microservices architecture experience' (too much glued-together specificity at once). When results are weak (<3 hits or only 'Alternative fit'), retry with a progressively simpler/broader query instead of asking the user, e.g. 'Senior mobile app developer for fintech startup' → 'Mobile app developer' → 'App developer' → 'Mobile development'; or 'GDPR compliance lawyer for healthcare startup' → 'GDPR lawyer' → 'Data protection lawyer' → 'Lawyer'."
    },
    "languages": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Only when the user explicitly asks for a specific specialist language (e.g. 'a Polish-speaking designer'). Allowed values: English, Polish, German, French, Spanish, Italian — any other value is rejected by the API. Omit the field (or []) when the user did not mention a language."
    },
    "country": {
      "type": "string",
      "description": "Only when the user explicitly asks for the specialist's country (e.g. 'a designer from Poland'). Full English country name, e.g. \"Poland\", \"Germany\" — not an ISO code. Ignored if geo_location is also given. Omit the field when the user did not mention a country."
    },
    "geo_location": {
      "type": "object",
      "properties": {
        "lat": {
          "type": "number"
        },
        "lon": {
          "type": "number"
        },
        "radius_meters": {
          "type": "number"
        }
      },
      "required": [
        "lat",
        "lon",
        "radius_meters"
      ],
      "additionalProperties": false,
      "description": "Only when the user gives a specific city/location and wants to search nearby (e.g. 'near Warsaw', 'a designer in Warsaw'). An object { lat, lon, radius_meters } — determine the lat/lon of the named city yourself. Default radius_meters is 50000 (50km); when there are too few results, raise it to 100000, then 200000 instead of broadening the query. Takes priority over `country` if both are given. Omit the field when the user did not mention a location."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 20,
      "description": "Default 10, raise to 20 for weak results or when the user asks for more options (max 20)."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Invites one or more chosen specialists to a project — does NOT charge payment. budget is a single amount for the whole task (not multiplied per specialist) — whoever accepts it does the work for it. Requires user_confirmed=true, set only after the user has explicitly confirmed in the conversation the choice of specialists, the list of shared files and the estimated cost. Estimate budget yourself from the problem's complexity (e.g. 1h = a single well-localized bug / a simple document fix / a minor graphic tweak; 2h = a standard debug across a few files / a draft legal document (e.g. Privacy Policy) / a landing page design; 3h = an architecture review, a full legal package (ToS+Privacy+GDPR) or a compliance audit, full branding, no clear diagnosis) times the specialist's min_rate_per_hour (from search_specialists) — this field is informational, not enforced, always in USD (the only currency on the marketplace).

{
  "type": "object",
  "properties": {
    "specialist_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "description": "Id of one or more specialists to invite."
    },
    "title": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "problem_context": {
      "type": "string"
    },
    "budget": {
      "type": "number",
      "minimum": 0
    },
    "timeline": {
      "type": "string",
      "enum": [
        "In a week",
        "In a month",
        "In 3 months",
        "No rush",
        "Do not know"
      ],
      "default": "No rush",
      "description": "How urgent the project is from the client's perspective — ask the user directly, do not guess."
    },
    "language": {
      "type": "string",
      "enum": [
        "English",
        "Polish",
        "French",
        "German",
        "Spanish",
        "Italian"
      ],
      "description": "The task's language — must match the language the user phrased title/description in (there is no auto-detection, set it according to the user's input)."
    },
    "context_files": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "content_base64": {
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": false
      },
      "description": "The minimal set of files the specialist needs. Each entry is { name, url?, content_base64? } and must carry exactly one source. `url` is strongly preferred: pass a link if the user gave one (Google Drive / Dropbox / S3 / raw GitHub) — the server rewrites common Google Drive and Dropbox share links to their direct-download form, and rejects a URL that returns a web page instead of a file — or, if you have a way to upload the file yourself (e.g. a code execution / shell environment) — upload it to any URL-reachable location first and pass that link instead of the raw bytes; the server just downloads it, which is fast and costs you almost no extra tokens. Use `content_base64` only as a last resort, when there is no URL and you have no way to produce one yourself (e.g. a small file the user attached directly in a chat-only client with no upload capability of its own) — inlining bytes means writing out the entire file as text, which is slow and burns far more tokens than a URL for anything beyond a tiny file. Before falling back to it, tell the user that creating the task will take noticeably longer and use more tokens because of it. Raw base64 only, never a `data:...;base64,` prefix. This server runs remotely and cannot read the caller's disk, so never pass local paths. The server scans every file for secrets, then uploads the rest to the task's file storage on Stoory; contents never enter the model context. Max 5MB per file. Entries that are unreadable or filtered as secrets come back in blocked_files — the task is still created without them."
    },
    "user_confirmed": {
      "type": "boolean",
      "description": "Must be true — set it only after the user's explicit confirmation in the conversation."
    }
  },
  "required": [
    "specialist_ids",
    "title",
    "description",
    "problem_context",
    "budget",
    "language",
    "user_confirmed"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns the whole task record in one call — use it both to check progress and to read the result. Fields: status, title, desc, budget, deadline, timeline, created, modified; specialist_invited and specialist_accepted (arrays of { id, profile_url } — profile_url is already in the right language, show it to the user as a link, not a bare id); and `files` — URLs of every file attached to the task on Stoory (the client's context files plus whatever the specialist delivers). Call it again when the user asks about progress. create_task already returns attached_files for the files it uploaded.

{
  "type": "object",
  "properties": {
    "task_id": {
      "type": "string"
    }
  },
  "required": [
    "task_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Cancels the task, as long as the specialist has not started work yet.

{
  "type": "object",
  "properties": {
    "task_id": {
      "type": "string"
    }
  },
  "required": [
    "task_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}