Stoory Hire Specialist

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

With no annotations provided, the description carries the behavioral burden. It discloses an important conditional behavior: cancellation is only possible before work has started. However, it does not mention what happens if the specialist has already started, whether cancellation is reversible, or what response can be expected.

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

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

A single sentence that states the action and the critical precondition without wasted words. The most important constraint is front-loaded and easy to parse.

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

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

For a simple single-parameter mutation tool, the purpose and precondition are present. However, with no annotations and no output schema, the description leaves out likely useful details such as error behavior when the task cannot be cancelled and whether the action is irreversible.

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

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

Schema description coverage is 0%, and the description does not explicitly explain the task_id parameter. The meaning is weakly implied by 'Cancels the task,' but the description does not compensate for the lack of parameter documentation.

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

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

The description names a specific verb ('Cancels') and resource ('the task'), and includes the key precondition. It is clearly distinct from its siblings, which create, retrieve, or search tasks rather than cancel them.

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

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

The description supplies the relevant condition for use: cancellation is valid only when the specialist has not started work. It does not explicitly mention alternatives, but none of the siblings perform a comparable cancel operation, so this is sufficient.

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

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

With no annotations, the description carries full burden and delivers: it discloses that no payment is charged, that budget is a single whole-task amount not multiplied per specialist and is informational/unenforced, and the context_files parameter description discloses side effects — server scans for secrets, pushes to a private GitHub repo, contents never enter model context, max 1 file ≈900KB, never local paths — plus the failure/retry flow for a missing GitHub username. This far exceeds what annotations would typically provide.

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

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

The main description is a run-on chain of clauses, but every clause earns its place: the budget heuristics and confirmation gate are operationally necessary, and context_files' paragraph prevents costly token-burning and disk-access mistakes. Length is justified density rather than padding, though it could be restructured into clearer sentences.

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

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

For a complex mutating tool with no annotations and no output schema, the description covers prerequisites, money semantics, file-handling rules, and a real failure mode (GitHub username — with a retry instruction). The main remaining gap is the unspecified return value and explicit lifecycle placement relative to search_specialists/cancel_task, which are minor against the depth present.

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

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

Schema description coverage is 56% — language, timeline, context_files, specialist_ids, and user_confirmed are documented in-schema. The main description compensates for the undocumented budget by adding an estimation methodology, USD currency note, and 'not enforced' semantics; context_files has exceptionally deep guidance (URL vs base64, token costs, size cap, secret scanning). title/description/problem_context stay bare but are self-evident string fields.

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

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

The opening clause states a specific verb+resource ('Invites one or more chosen specialists to a project') that is immediately distinguishable from the sibling family of cancel/get/search tools. It loses the fifth point because it does not explicitly name a sibling it is not, though the family contrast is obvious.

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

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

Sets an explicit, enforceable prerequisite — user_confirmed=true only after the user explicitly confirmed specialists, shared files, and estimated cost in the conversation — telling the agent when it is permitted to call this tool. It also references search_specialists for min_rate_per_hour to derive the budget. No explicit when-not-to-use or alternative-naming, but as the sole creation tool in the family the context is sufficient.

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

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

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses read-only file access, root-directory-only scope (flat repo), and the 900KB threshold where content is replaced by a download_url. It doesn't describe the exact normal-file return shape, but the key limitations are explicit.

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

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

Two sentences with no filler: the core action and source are front-loaded, and the constraints are packed into a compact second sentence. Every clause adds decision-relevant information.

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

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

For a single-parameter read tool with no output schema, the description covers the source of repo_url, the flat/root-only structure, and the large-file truncation rule. It leaves minor gaps about the exact normal-file return format, but an agent has enough to select and invoke the tool correctly.

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

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

The schema documents only task_id as a required string with no description (0% coverage), so the description must compensate. It clarifies that task_id refers to the task whose GitHub repo is being read and that repo_url comes from get_task_result or create_task. It does not restate the parameter formally, but the mapping is unambiguous.

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

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

The description opens with a specific verb and object: 'Reads the contents of files from the task's GitHub repo,' and ties it to the repo_url returned by get_task_result or create_task. This clearly differentiates it from sibling task-management tools such as cancel_task, get_task_status, and search_specialists.

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

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

It gives concrete usage context: use this tool to check a specialist's work without manually opening the link, and it identifies the prerequisite of obtaining repo_url via get_task_result or create_task. It doesn't explicitly mention when not to use it, but no sibling performs file reads, so the context is sufficient.

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

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

With no annotations, the description carries the transparency burden. It discloses the two main outputs—status and repo link—and clarifies that files, commits, and diffs are not returned inline but live in the repo. It does not mention edge cases such as missing repo link or task-not-found behavior, but for a simple query tool the disclosure is minimally adequate.

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

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

Two concise sentences with no filler, and the primary output (status + repo link) is front-loaded. The second sentence earns its place by explaining where the specialist's actual work can be found.

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

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

The description covers the core result and usefully points to the repo for files, commits, and diffs. However, with no output schema and a sibling named get_task_status, it should have clarified when get_task_result is preferred and what the response contains when no repo link exists.

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

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

Schema description coverage is 0%, and the description does not mention task_id, its meaning, format, or how it relates to the returned result. The parameter name is self-explanatory, but the description adds no semantic value beyond what the schema already provides.

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

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

The description clearly states the verb 'Returns' and the resource: the task's status and GitHub repo link. It also adds useful context that the specialist's work lives in the repo, but it does not explicitly distinguish itself from the sibling get_task_status, which also likely returns status.

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

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

Usage is implied: call this to get the task result and the repo link where the specialist's work is stored. The note about create_task returning repo_url when attachments exist hints at an alternative source, but there is no explicit when-to-use or when-not-to-use guidance versus get_task_status or get_task_repo_files.

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

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

There are no annotations, so the description carries the full burden. It discloses that the response includes specialist_accepted/specialists_invited with profile_url fields, instructs the agent to render them as links, and notes the language is already correct. It doesn't describe side effects, but the action is explicitly a check, so read-only behavior is reasonably evident.

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

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

Two sentences with no wasted words. The first states the purpose, the second adds a usage trigger and a valuable output-handling note. Everything present earns its place, and the key information is front-loaded.

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

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

For a single-parameter status tool with no output schema, the description covers the essential details: what it does, when to call it, and how to handle the notable response fields. It doesn't list possible status values or error conditions, but those are not required for an agent to select and invoke correctly.

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

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

The schema has 0% description coverage for task_id, and the description doesn't explicitly explain the parameter. However, the parameter name and the description's reference to 'the task' make its meaning obvious, so the lack of explicit parameter documentation is only a minor gap.

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

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

The description states a specific verb and resource: 'Checks the task's current status.' It naturally differentiates from siblings like get_task_result by emphasizing progress rather than final output, and the 'Call it again' phrasing clarifies its role as a status poll.

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

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

It provides an explicit usage trigger: 'Call it again when the user asks about progress.' It doesn't name alternatives or state when not to use it, but the distinction from get_task_result and the simple tool set make the appropriate context clear.

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

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.

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.

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.

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.

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.

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.