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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, but the description adds substantial behavioral context beyond them: the server-side state machine, next_action handling, use of native question pickers, temporary test credentials, and verification ownership. This is exactly the kind of protocol detail an agent needs to invoke the tool correctly.

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 description is long but front-loads purpose, usage, and behavior in a structured way. For a complex orchestrator, most sentences earn their place, though the turn-by-turn protocol is dense and could be tightened slightly without losing necessary meaning.

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 high complexity, lack of an output schema, and stateful conversational protocol, the description is complete enough for correct invocation. It explains the return flow through next_action values, session_id reuse, tool_call handling, and completion without requiring the agent to infer missing behavior.

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%, so the schema already documents all four parameters thoroughly. The description mainly repeats those requirements, such as intent only on the first call and user_response after wait_for_user, and adds only minor extra context about passing picker values versus freeform text.

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: a conversational integration coach that orchestrates adding an API integration in FetchSandbox. It clearly distinguishes itself from siblings by positioning the tool as the entry point to call before any other FetchSandbox tool for open-ended integration requests.

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 a clear when: call before any other FetchSandbox tool when the user has an open-ended 'help me add X', 'integrate X', or 'test my X integration' ask. It also provides a detailed turn-by-turn protocol, but it does not explicitly name when-not to use it or name specific sibling alternatives such as run_workflow or validate_integration.

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?

Annotations already mark it read-only and non-destructive, and the description adds valuable behavior: it packages local uncommitted code without a git URL, runs for minutes, and produces hypotheses rather than confirmed proofs. This goes well beyond the safety profile already conveyed by annotations.

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 most important guidance is front-loaded: FIRST STEP, examples, and the finding-not-proof caveat. The longer symptom list and repeated emphasis on the next actions are purposeful and reinforce the critical workflow 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 no output schema, the description still tells the agent what the response will contain (next_actions) and to follow it. It covers runtime, scope, optional path behavior, and the limitation that findings are hypotheses, making the definition complete for correct invocation.

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%, so all three optional parameters are already documented with meaning. The description adds contextual color about the project being analyzed, but no parameter-level semantics beyond what the schema provides, so the baseline score of 3 is appropriate.

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?

States an explicit purpose: it is the FIRST STEP for API-integration bug discovery, auditing the current project against a corpus of known failure classes. It clearly distinguishes itself from siblings by calling itself a finding, not a proof, and by being the audit step before fix_bug and prove_fix.

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?

Gives explicit when-to-use context with concrete symptom examples, and explicitly says not to stop here or write a test, directing the agent to fix_bug and prove_fix. It even tells the agent to follow next_actions, making the routing unambiguous.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description consistently reinforces this by stating 'it does NOT modify your files'. It adds valuable behavior beyond the annotations: the project is shipped to FetchSandbox runtime, the tool authors a minimal fix, the result is a git diff, and runtime can take up to a few minutes.

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?

Three sentences carry a lot of precisely relevant information: what the tool does, what it does not do, how long it runs, and what the user should do next. There is no filler, and the most important caveat 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?

Given 5 parameters, no output schema, and annotations that already cover read-only/destructive behavior, the description is complete enough for correct invocation. It tells the agent the input source (find_bugs), the output (git diff), the non-mutating behavior, the runtime bound, and the follow-up proof step.

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%, so the input schema already documents each parameter in detail. The description adds workflow-level context (e.g., bug should come from a find_bugs finding, and fix_pattern relates to the guide's matched_bug_pattern), but it does not materially expand parameter semantics 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 states a clear verb+resource: 'get a proposed fix for a specific bug in YOUR code', and explicitly names its role as 'The fix step after find_bugs'. It differentiates from siblings by emphasizing it returns a git diff and does not modify files, so an agent can distinguish it from prove_fix, submit_proof, and verify_behavior.

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 explicit usage context: use it after find_bugs, and after applying the diff prove the fix using submit_proof or verify_behavior. It also warns that the diff is a proposal not a proof, which is a clear when-to-use/when-not-to-use boundary.

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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by explaining the routing logic and the return shape ('Returns {spec, workflow, scenario, confidence, reasoning} plus next_actions'), which is not redundant with annotations. It does not contradict any annotation.

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 description is longer than average but every sentence serves a purpose: it defines the tool's unique value, explains the failure class it addresses, and outlines the output. The key action ('ROUTE a symptom...') is front-loaded, and the subsequent examples are illustrative, not filler. It could be tightened slightly but is not wasteful.

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 (routing across providers and domains) and the absence of an output schema, the description compensates by explicitly listing the return fields and next_actions. It also explains the reasoning behind its use, making it complete for an agent to decide when to call it and what to expect. No critical information is missing.

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%, so the baseline is 3. The description adds meaningful guidance beyond the schema, particularly for the intent parameter: 'Don't pre-process or shorten — the router benefits from the full phrasing (capture timing, geo cues, failure mode language)'. This is concrete, behavioral guidance that improves correct usage, justifying a 4.

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 'ROUTE a symptom to the provider behaviour that explains it', stating a specific verb and resource, and clearly distinguishes itself from code-reading and documentation tools by explaining what it does NOT do ('not what its docs say, and not what can be inferred from reading the integration code'). This makes its purpose unmistakable and separates it from siblings like find_bugs or fix_bug.

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?

Explicitly provides a use condition ('Use this when the user names a provider or a domain...') and explains why alternatives fail (code cannot reveal provider meaning). It also instructs the agent to 'Follow it rather than improvising the next step', giving clear post-call guidance. This is strong, actionable usage direction.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read. The description adds behavioral context beyond annotations by noting that each run includes a shareable timeline URL (fetchsandbox.com/runs/<sandbox_id>) and that the server may cap the limit. This gives the agent a preview of the return payload and server-side behavior, which is useful. No contradictions with annotations.

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 description is compact and front-loaded: it opens with the tool's core function and ordering, then immediately gives usage triggers, then explains the output benefit (shareable URLs). Every sentence earns its place—there is no filler or repetition. The length is appropriate for the tool's complexity, and the logical flow (what → when → output) helps an agent parse it quickly.

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?

There is no output schema, so the description carries the burden of explaining what the tool returns. It mentions that runs include a shareable timeline URL, which is the most important output detail for sharing/re-inspection. It also clarifies that it covers ad-hoc traffic, and notes the limit default/cap. However, it does not enumerate other fields of each run (e.g., run ID, status, timestamps) that might be expected from a list endpoint. Given the tool's simplicity and the described use cases, this is a minor gap; the description is still largely complete.

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 input schema already covers both parameters (limit and sandbox_id) with descriptions, achieving 100% coverage. The description adds extra semantic value by clarifying that sandbox_id comes specifically from import_spec, and that limit may be capped by the server, which the schema does not mention. This goes beyond the baseline expectation for high schema coverage, so a 4 is warranted.

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?

Clearly states the tool lists recent workflow runs and ad-hoc traffic for a sandbox, newest first. The verb is specific ('list'), the resource is specific ('recent workflow runs'), and it distinguishes from siblings like list_workflows by focusing on runs rather than defined workflows. The description also gives concrete example queries, making the purpose unmistakable.

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?

Explicitly enumerates when to use the tool: 'Use when the user asks "what did I run", "show me recent validation runs", "did the stripe test pass earlier", or wants to find a previous run to share or re-inspect.' It also states the required prerequisite (sandbox_id from import_spec), leaving no ambiguity about invocation conditions. While it doesn't state when not to use it, the positive triggers are clear and the tool is distinct from siblings, 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it explains that the tool returns each scenario's name and what it does, and that scenario names differ per provider. It also implies the tool is a read-only discovery operation, consistent with annotations. Minor gap: it doesn't specify pagination or ordering, but that's not critical for a list operation.

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 description is moderately long but every sentence earns its place: it defines the resource, gives usage timing, explains why the tool matters, provides example scenario names, notes provider variability, and routes to the next step. It is front-loaded with the core purpose ('List the FAILURE SCENARIOS') and the critical usage instruction ('Call this BEFORE claiming an integration works'). Slightly verbose in the middle with the example list, but that list adds concrete value for an agent.

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 list tool with one parameter, 100% schema coverage, and annotations covering safety, the description is nearly complete. It explains what the return value contains (each scenario's name and what it does), which is useful since there is no output schema. It also provides the workflow context (list then set_scenario). It doesn't mention error cases or empty results, but those are minor for a discovery tool.

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%, so the schema already documents the single parameter sandbox_id. The description mentions sandbox_id indirectly by referencing 'this sandbox' and the sibling set_scenario, but doesn't add new semantic detail about the parameter beyond what the schema provides. Baseline 3 is appropriate since the schema carries the parameter documentation burden.

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 ('List') and resource ('FAILURE SCENARIOS this sandbox can inject on demand'), and explains what these scenarios are (specific ways the real provider misbehodes in production). It distinguishes itself from siblings by framing the tool as the discovery step before using set_scenario, and by noting that scenario names differ per provider, so listing is necessary rather than guessing.

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 explicit when-to-use guidance: 'Call this BEFORE claiming an integration works.' It explains why the happy path is insufficient and that the tool should be used to discover provider-specific failure scenarios. It also names the sibling set_scenario as the next step ('Arm one with set_scenario'), providing clear routing between related tools.

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?

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description adds meaningful context beyond that: the return structure (slug, description, endpoint count, tags) and how the slug feeds into import_spec. OpenWorldHint ('40+ more') is honored without contradiction.

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?

Resource is front-loaded first, then usage triggers, then return format, then filter example — a logical, scannable order. Slightly long, but each sentence contributes (concrete API names, query phrases, downstream slug usage, filter example), so no waste.

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?

A low-complexity tool (one optional param) with no output schema, so the description rightly takes on the return-format burden, which it meets. The only minor gap is no mention of result limits or pagination, but that's immaterial for a simple catalog browse tool.

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 coverage is 100% — the schema already fully documents the filter param (case-insensitive substring, matches name/slug/description/tags, omit for full catalog). The description's filter example (filter='pay') is a nice illustration but adds little beyond what the schema states, so the high-coverage baseline of 3 applies.

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?

States a precise verb ('Browse') and a specific resource ('FetchSandbox spec catalog') with concrete examples of covered APIs (Stripe, GitHub, Twilio, etc.). It implicitly differentiates from siblings like list_workflows (workflows, not specs) and import_spec (the consumer of the returned slug).

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?

Gives explicit query triggers ('what APIs do you support?', 'do you have <X>?') and the decision context 'before committing to one', which routes the agent to import_spec afterward. This is as explicit as it gets for a browse tool without listing every sibling as a negative case.

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?

Annotations already cover read-only/idempotent/non-destructive behavior. The description adds meaningful non-obvious behavior: the tool returns failure scenarios alongside workflows and instructs the agent to read them to the user and ask which matter. This goes beyond the annotations and clarifies the tool's side effects on the conversation flow.

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 description is longer than typical but information-dense: purpose, example, usage context, chaining instruction, return content, and user-interaction rule all earn their place. It is front-loaded with the core purpose, though it could be tightened by moving the workflow example later.

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?

With no output schema, the description compensates by explaining what the result contains ('workflows AND failure scenarios', each with descriptions and an exact call), and it tags the critical interaction requirement around scenario selection. The parameter usage, sibling chaining, and result semantics are all covered.

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 both spec_id and spec_slug are documented in the input schema. The description does not add syntax-level parameter detail beyond the schema, and the usage context ('after import_spec') is also present in the schema description for spec_id.

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 clear verb+resource: 'List the named, runnable workflows for a previously-imported spec' and gives an illustrative workflow example. It does not explicitly distinguish itself from the sibling list_scenarios, despite the fact that both this tool and that sibling appear to deal with scenarios, so it stops short of full sibling differentiation.

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 explicitly prescribes when to call it: after import_spec for exploration, or before run_all_workflows for scoped validation, with a concrete chaining pattern ('list, filter by user intent, then pass matching ids'). It also gives a behavioral instruction for the scenario results, telling the agent not to guess scenario names and to ask the user which matter.

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?

Annotations already say readOnlyHint=false and destructiveHint=false, and the description adds valuable behavior beyond that: the tool builds its own before/after copies, never writes to the user's tree, applies the diff to a copy, requires a measured before/after flip, and refuses paths outside the workspace. It does not fully disclose failure-mode or pass-vs-error semantics, which keeps it from a 5.

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 description is dense and imperative, with front-loaded purpose and clear ordering constraint. It is longer than average and includes some repetition and all-caps emphasis, but nearly every sentence carries operational significance; a small amount of rhetorical repetition ('only way', 'DO NOT SUBSTITUTE', 'never') costs it one point.

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 six-parameter tool with no output schema, the description explains the core behavior (applies diff to a copy, runs same probe, measured flip), security/order constraints, and parameter idioms. It does not describe the result receipt shape, error cases, or what happens when the flip is not observed, which an agent would need to interpret the tool's output.

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 input schema already covers 100% of parameters with descriptions, so the baseline is 3. The description goes above the schema by explaining the significance of 'diff' (must come from fix_bug), 'path' (do not copy the project; outside paths refused), and 'sandbox_id' (usually omit; last twin auto-attached). This is genuine added value beyond the schema text.

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 ('prove'), a precise mechanism (FetchSandbox applies the diff to a copy and runs the same failure probe against buggy and fixed trees), and a measurable success condition (green only on a measured flip). This makes it clearly distinct from siblings like verify_behavior, fix_bug, or submit_proof, and from an agent's own ad-hoc test.

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 explicit timing ('CALL THIS BEFORE YOU WRITE THE FIX TO DISK'), explains why ordering matters (the broken tree is needed for reproduction), and explicitly warns against substituting a custom harness with the rule that such a check must never be reported as proven or verified. This is strong when-vs-when-not guidance with clear user-facing consequences.

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?

Annotations already declare readOnlyHint=false, openWorldHint=true, and destructiveHint=false for the safety profile; the description adds meaningful behavioral context beyond that — it spins up a sandbox as a side effect, requires no prior sandbox_id, and discloses the exact return contract (sandbox_id + flow_run_id + receipt URL) with chaining guidance to verify_behavior. This exceeds baseline transparency for a state-changing tool.

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?

Four dense sentences, front-loaded with the core purpose and key differentiator (no import_spec needed). Every subsequent sentence earns its place: the normal call path, scenario reproduction, return contract, and the run_workflow exclusion. Slightly long, but no wasted words given the routing and chaining information it must carry.

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?

Complete for a tool with no output schema: it discloses return values (sandbox_id, flow_run_id, receipt URL), preconditions (no import_spec needed), the failure-reproduction parameter path, and the surrounding workflow (guide → quickrun → verify_behavior). An agent has everything needed to invoke it correctly in context.

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%, so the baseline is 3 and the schema already documents all three parameters, including where to source them ('from guide') and the scenario semantics. The description reinforces these sources with concrete examples (stripe, accept_payment, webhook_retries) but adds little meaning the schema doesn't already provide.

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?

States a specific verb and resource ('Run a curated proof workflow against a KNOWN, bundled spec') and immediately distinguishes itself from siblings: it does NOT need import_spec or a sandbox_id, and it is explicitly differentiated from run_workflow at the end. An agent can tell exactly what this tool is for and how it differs from its peers.

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?

Gives explicit when-to-use guidance: 'This is the normal path when the user is testing an integration with a well-known provider: call guide... then call quickrun.' It also names the alternative and its condition: 'Use run_workflow instead ONLY when you already hold a sandbox_id from import_spec of a custom/private spec.' Nothing is left to inference.

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?

Annotations only provide flags (readOnlyHint=false, destructiveHint=false), so the description must fill in behavior. It discloses that this is a write/mutating operation (runs workflows), reduces UI approvals, and returns a summary plus full step trace. It also mentions the shareable timeline link. Slightly less than 5 because it doesn't detail failure behavior, but it covers key points.

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 description is information-dense and front-loads the primary use case early with 'Execute EVERY workflow... in ONE call.' It then explains usage, scoping, and returns concisely. Slight padding with the IDE click explanation could be trimmed but serves a purpose for user context. Overall, it's structured effectively.

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 (batch execution), the description provides sufficient usage context, scoping options, and return information. It lacks a detailed list of possible failure modes or timeouts, but since there's no output schema and annotations are minimal, it does well. A 4 is justified as it could be more complete with error handling, but it's solidly above average.

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 coverage is 100%, covering sandbox_id and workflow_names. The description adds value by explaining how workflow_names scopes the subset with examples, and clarifies case-insensitivity and character interchangeability, beyond the schema's brief notes. It reinforces the semantics, which is helpful. A 4 is appropriate since it's not adding entirely new meaning but contextualizes the schema.

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 tool executes every workflow (or a subset) for a sandbox in one call, and distinguishes it from run_workflow. It provides a strong verb (execute), specific resource (workflows for a sandbox), and concrete use cases (validate, run all workflows), making its purpose unmistakable.

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 explicitly tells users to use this instead of a loop of run_workflow, and gives concrete examples of when to use it ('validate this integration', 'run all workflows', etc.). It also explains how to scope with workflow_names, including case-insensitivity and dash/underscore handling, so an agent knows exactly when and how to invoke it.

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?

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, and the description is consistent with all of them (execution implies side effects; webhook events align with openWorld). The description adds genuine value beyond annotations: the scenario toggling behavior (set for the run's duration then restored), the canonical status of share_url, and the instruction not to substitute a docs URL as proof. No contradictions found.

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 description is longer than average but every sentence earns its place — primary action first, then output semantics, then usage rules and alternatives. It is front-loaded with the core action before the routing guidance. Slightly verbose in the exclusion list, but dense with actionable information rather than filler.

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?

With no output schema present, the description correctly takes on the burden of explaining the return value (trace + share_url) and its role as the proof artifact. The tool is simple (3 params, 2 required, no enums, no nesting) and the description fully covers invocation, output, and routing — an agent has everything needed to call it 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?

Schema description coverage is 100%, with each parameter (scenario, sandbox_id, workflow_name) already well documented including case-insensitivity and scenario-restore semantics. The description reinforces the workflow_name routing and scenario intent but does not add parameter details beyond what the schema provides, so baseline 3 is appropriate.

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 ('Execute ONE specific workflow by name') plus the precise output contract (step-by-step trace and a share_url proof artifact). It clearly distinguishes itself from run_all_workflows by contrasting single-workflow execution against batch validation, so an agent can tell them apart without opening either schema.

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?

Extremely explicit about when to use it ('Use ONLY when the user explicitly names a single workflow') and when not to, naming the alternative (run_all_workflows) with concrete examples of ambiguous intents like 'validate stripe checkout' where multiple workflows match. Also flags calling this in a loop as an anti-pattern. Nothing is left to inference.

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?

Annotations indicate non-read-only, open-world, idempotent, and non-destructive. The description adds that the scenario persists until changed and affects all callers of the sandbox, which is critical behavioral context beyond annotations. It also emphasizes the importance of resetting, fully disclosing side effects.

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 description is a single paragraph of about 150 words, covering purpose, usage, restoration, and warnings. While not as tight as a two-sentence description, every sentence contributes to correct usage, so it is appropriately sized and front-loaded with the core action.

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 tool with two parameters and no output schema, the description covers the intended workflow, restoration, and side effects. It is complete for an agent to know when and how to invoke it correctly, including the need to verify end state and reset after testing.

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 input schema already provides thorough descriptions for both parameters, including valid values for scenario and failure behavior on unknown names. The description adds usage context but no new parameter-specific semantics, so the baseline of 3 is appropriate given 100% schema coverage.

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 (ARM) and resource (failure scenario on a sandbox), clearly distinguishing it from list_scenarios. It explains the purpose of testing integration resilience, leaving no ambiguity about what the tool does.

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 an explicit step-by-step workflow: run on 'default', arm a failure from list_scenarios, re-run, verify end state, and restore with 'default'. It also warns about side effects and the need to reset, making when and how to use it unambiguous.

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?

Annotations already indicate readOnlyHint=false and destructiveHint=false, but the description adds critical behavioral context: this is self-reported evidence that 'never counts as a proven (green) result'. It also discloses that receipts are public and the submission is non-authoritative. This goes well beyond annotations and prevents misinterpretation.

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 description is detailed but every sentence earns its place: it front-loads the privacy warning, then gives usage timing, then explains the self-reported nature and contrast with prove_fix, then parameter guidance. It is structured logically and avoids redundancy with the schema.

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 tool with 5 parameters, nested objects, and no output schema, the description covers everything an agent needs: when to use it, what to attach, how to structure proofs, keying to run IDs, and its non-green status. The presence of an alternative (prove_fix) is clearly stated, so the agent can make an informed choice.

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 coverage is 100%, so parameters are already documented. However, the description adds operational semantics by instructing 'Provide one proofs entry per probe you fired' and explaining the expected structure (request, before, after) and keying to sandbox_id + flow_run_id. This adds value beyond the schema's field definitions, though it could have gone further with concrete examples.

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 explicitly states the tool's purpose: to submit self-reported proof of a bug fix by attaching real before/after evidence from the user's app to the run receipt. It clearly distinguishes itself from the sibling tool 'prove_fix' by contrasting self-reported vs measured green proof, so an agent can tell them apart without opening schemas.

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 explicit when-to-use guidance: 'Use this AFTER you've fixed the bug and re-run the app'. It also names the alternative (prove_fix) for measured green proof and explains the condition (when you want FetchSandbox verification). Additionally, it warns about public visibility of receipts, which is an exclusion condition for sensitive content.

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?

Annotations only declare the generic safety profile (readOnlyHint=false, openWorldHint=true, non-idempotent, non-destructive); the description adds far more: it returns fresh twins and credentials, requires host-side setup, expects a 400 preflight and treats a 307 as a blocker, mandates secret cleanup, and warns that logs/receipt pages do not prove production readiness. No contradiction with the annotations.

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 first sentence is front-loaded and much of the content is substantive, but the body is a single undifferentiated wall of operational policy that would benefit heavily from structure. Length is defensible for a 10-parameter, multi-phase tool, yet the lack of headings/grouping makes it harder to parse than it needs to be.

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?

Despite having no output schema, the description explains return shapes (matrix before traffic, next_action, configure_app's URLs and secret_handoff_url, execution_diagnostics), covers credentials, preflight, checkout-vs-API separation, and cleanup. An agent has enough to call it correctly and interpret results.

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 coverage is already 90%, so the baseline is 3, but the description adds real operational meaning: arm/probe/cancel/run_id dependencies, the value of receipt_recovery_v1 (R1-R4 plus R5-R8 scenarios), the need for an exact published webhook URL in receipt_config, and that configure_app returns URLs and secret_handoff_url rather than values. This exceeds what the schema alone conveys.

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?

Opens with a specific verb+resource ('Start a validation session for the user's integration') and explicitly contrasts itself with siblings quickrun/run_workflow, explaining that those test provider-vs-twin behavior while this tests whether the app itself is wired correctly. An agent can distinguish it from every listed sibling without opening a schema.

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?

Gives explicit when-to-use ('when someone wants their integration verified before launch'), when-not ('do not substitute guide, quickrun, list_workflows, or reference probes'), and sequencing rules (call once with providers, then follow next_action; never execute while host-side setup is pending). The alternative tools are named and excluded.

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?

Annotations already declare it is not read-only and is open-world, so the bar is lower; the description still adds rich behavioral detail — the backend spawns both a buggy and a fixed reference handler, fires the probes at each, and returns a side-by-side diff. It also discloses that the handlers are FetchSandbox reference implementations, not the user's code, which prevents a serious misinterpretation of the result.

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?

Dense and multi-clause, but front-loaded with the core action and every sentence carries distinct information (lifecycle position, side effects, parameter wiring, scope caveat). No filler, though it runs longer than strictly necessary.

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?

A multi-step orchestration tool with no output schema; the description explains what is produced (side-by-side diff with a concrete example), where it is persisted (receipt URL), and what the result does and does not prove. Nothing needed to call it correctly is missing.

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 coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: sandbox_id and flow_run_id must be passed together to bind the pattern to a provider and save the diff onto that run's receipt, and bug_pattern_id's provenance (guide's matched_bug_pattern) is spelled out.

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?

States a specific verb and resource ('Prove a known fix survives a bug') and frames itself as the 'prove' half of a reproduce→prove pair, explicitly distinguishing it from run_workflow. An agent can tell exactly what this does without opening the schema.

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?

Gives an explicit trigger ('Call this AFTER run_workflow reproduces a failure, when the matched bug_pattern has a simulation block') plus a clear limit ('a confirmed reference result does not verify the user's app'). Both when-to-use and when-not are stated.

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