Skip to main content
Glama

Stoory Hire Specialist

by io.github.StooryBot
OverviewDiscussionsAdmin

Search specialists

search_specialists

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoDefault 10, raise to 20 for weak results or when the user asks for more options (max 20).
queryYesThe 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'.
countryNoOnly 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.
languagesNoOnly 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.
geo_locationNoOnly 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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • changedInput schema / properties / country / description
      Previous value: -"Tylko gdy user jawnie prosi o kraj specjalisty (np. 'grafik z Polski'). Pełna angielska nazwa kraju, np. \"Poland\", \"Germany\" — nie kod ISO. Ignorowane, jeśli podano też geo_location. Pomiń pole, gdy user nie wspomniał o kraju."New value: +"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."
    • changedInput schema / properties / geo_location / description
      Previous value: -"Tylko gdy user podaje konkretne miasto/lokalizację i chce szukać w okolicy (np. 'w okolicy Warszawy', 'designer w Warszawie'). Obiekt { lat, lon, radius_meters } — ustal lat/lon wskazanego miasta samodzielnie. Domyślny radius_meters to 50000 (50km); przy zbyt małej liczbie wyników zwiększaj do 100000, potem 200000 zamiast poszerzać query. Ma priorytet nad `country`, jeśli oba podane. Pomiń pole, gdy user nie wspomniał o lokalizacji."New value: +"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."
    • changedInput schema / properties / languages / description
      Previous value: -"Tylko gdy user jawnie prosi o konkretny język specjalisty (np. 'polskojęzyczny grafik'). Dozwolone wartości: English, Polish, German, French, Spanish, Italian — inna wartość zostanie odrzucona przez API. Pomiń pole (lub []), gdy user nie wspomniał o języku."New value: +"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."
    • changedInput schema / properties / limit / description
      Previous value: -"Domyślnie 10, zwiększ do 20 przy słabych wynikach lub gdy user prosi o więcej opcji (max 20)."New value: +"Default 10, raise to 20 for weak results or when the user asks for more options (max 20)."
    • changedInput schema / properties / query / description
      Previous value: -"Rola i umiejętności specjalisty, MAKS. 12 słów, naturalny język — nie pełne zdanie opisujące problem usera. Po angielsku, jeśli to możliwe (szybsza odpowiedź i lepsze trafienia niż w innych językach). Dobrze: 'Senior Stripe developer', 'Professional logo designer', 'Experienced UX designer for mobile apps'. Źle: 'I need someone who can help me with branding and visual identity design' (pełne zdanie zamiast roli), 'Full-stack developer with microservices architecture experience' (za dużo naraz sklejonej specyfiki). Gdy wynik słaby (<3 trafień lub same 'Alternative fit'), ponawiaj ze stopniowo prostszym/szerszym query zamiast dopytywać usera, np. 'Senior mobile app developer for fintech startup' → 'Mobile app developer' → 'App developer' → 'Mobile development'; albo 'GDPR compliance lawyer for healthcare startup' → 'GDPR lawyer' → 'Data protection lawyer' → 'Lawyer'."New value: +"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'."
  2. First observed

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full disclosure burden. It reveals genuinely useful behavioral traits: result quality depends on query construction, weak results manifest as '<3 hits or only Alternative fit,' and the expected agent behavior is an autonomous retry loop with an escalation threshold. It does not explicitly declare read-only safety, but 'Searches ... via semantic search' strongly implies a non-mutating operation, and no auth/rate-limit context is given.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The main description is two sentences (~70 words), purpose front-loaded, with every clause carrying actionable guidance — the weak-result condition, the retry instruction, the ~3-attempt threshold, and the user-facing fallback message. There is minor overlap where the retry rule reappears in the query schema description, but the description adds the escalation threshold not stated there, making the overlap complementary rather than padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity — 5 parameters, a nested geo_location object, and retry semantics — the description plus schema cover purpose, per-parameter inclusion rules, query-construction guidance, and the failure escalation path. No output schema exists, but the description references the result's key interpretive signals ('<3 hits,' 'Alternative fit'), giving the agent enough to judge result quality; a formal return-payload spec is the main missing piece.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema's per-parameter guidance is unusually rich: query has a 12-word limit with good/bad examples, and country/languages/geo_location all state explicit include-only-when-asked conditions and priority rules. The main description only points to the query field description rather than adding new parameter meaning, so the high-coverage baseline of 3 applies without upward adjustment.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Searches for specialists in the Stoory marketplace via semantic search,' naming the domain, the target entity, and the mechanism. The sibling tools are all task-lifecycle operations (cancel_task, create_task, get_task_status), so there is no plausible confusion between this marketplace-search tool and any sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives an explicit failure-handling protocol: retry with a simpler/broader query instead of asking the user, and only after ~3 failed attempts tell the user there is no one to recommend and suggest widening criteria. It does not explicitly contrast with sibling tools, but none of them are search alternatives; the guidance centers on the retry loop rather than tool selection, so an explicit 'when not to use' is less critical here.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Stoory Hire Specialist toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources