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

Annotations only cover the safety profile (readOnly/idempotent/openWorld), and the description goes well beyond them: server-side state machine ownership, twin bindings as temporary TEST credentials, never asking for live Paddle/Resend keys, never claiming unverified checks passed, and the rule to ask only for genuine access/secret/ambiguous-business-rule facts. That is rich operational context an agent cannot infer from 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?

Purpose is correctly front-loaded, but the body is roughly 450 words of dense prose mixing routing rules, safety policy, and credential guidance, with some redundancy ('the state machine is server-side' / 'let the server drive' / 'don't predict the next step'). The numbered turn protocol helps, yet the whole would benefit from tighter structure.

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, and the description compensates by explaining the return contract in prose (the next_action states and how to handle each) along with credential, verification, and routing semantics. For a multi-turn orchestrator with four optional parameters, nothing essential to correct invocation 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% and each of the four parameters is already documented (intent first-call-only, session_id after the first call, user_response after wait_for_user, context). The description restates the same call protocol rather than adding new syntax, formats, or constraints, so the baseline 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?

Names a specific role and resource ('conversational integration coach', 'server-side orchestrator that walks the user through adding an API integration') and enumerates its actual functions: intake, discovery questions from brain.yaml, workflow routing, FetchSandbox proof, compliance notes. It also differentiates itself from siblings by stating it must be called BEFORE any other FetchSandbox tool for open-ended integration asks.

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 ('open-ended help me add X / integrate X / test my X integration') and explicit when-not ('DON'T try to predict the next step or skip ahead'), plus the per-turn routing rules for act_in_app, wait_for_user, call_tool, and done. It also names the alternative path indirectly by insisting the server, not the caller, selects workflows and the verifier owns the verdict.

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 cover the safety profile (readOnlyHint, openWorldHint, destructiveHint false), but the description adds substantial behavior they cannot convey: it is long-running (up to a few minutes), it returns status:running/next_tool_call rather than a blocking result, it packages local/uncommitted/private code with no git URL required, and its output is a hypothesis rather than a proof. These are non-obvious operational facts an agent must know before invoking.

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?

Front-loaded with the single most important operational fact (do not poll, follow the job) and otherwise dense with useful workflow content. It is long and the 'do not stop here' / 'follow next_actions' points are restated in adjacent sentences, costing a little efficiency, but nearly every sentence carries weight for a multi-step workflow tool.

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, yet the description still tells the agent what comes back (status:running, next_tool_call, next_actions), how long it takes, and what to do with the result. Combined with the 100% covered input schema, nothing an agent needs to call this 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 all three optional parameters (path, spec, timeout_s) are already fully documented, including defaults and the max on timeout_s. The description adds no format or semantic detail beyond the schema, so the 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?

States a specific verb+resource (packages the project and audits it against a corpus of harvested API-integration failure classes) and enumerates the exact symptom classes it targets (webhooks, payments, auth, idempotency, signature verification). An agent can distinguish it from fix_bug and prove_fix without opening any schema, since the description names those siblings and their roles.

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?

Explicit when-to-use ('FIRST STEP for any API-integration bug', 'the moment a user reports a symptom'), explicit when-not ('never repeat this tool to poll', use get_job instead), and explicit alternatives in the workflow ('call fix_bug for a proposed diff, then prove_fix to measure it'). This is about as complete a routing instruction as a description can carry.

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 declare a safe read (readOnlyHint=true, destructiveHint=false); the description reinforces this with 'it does NOT modify your files' and adds context the annotations do not carry: async job semantics (status:running, next_tool_call:get_job), runtime up to a few minutes, and the caveat that the diff is a proposal, not a proof. No contradiction with the readOnly 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?

Front-loads the highest-risk operational fact (async job / never poll), then purpose, then the review-before-apply workflow. Dense but each sentence carries instruction or constraint; slightly long and the async aside competes with the core purpose at the top.

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, multi-step, asynchronous tool with no output schema, the description supplies the return shape (git diff, status:running, next_tool_call), the duration expectation, and the full downstream handoff to prove_fix. An agent has everything needed to call and chain 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: the 'bug' value should be a find_bugs finding ('file:line — description'), fix_pattern should come from guide's matched_bug_pattern, and it stresses not copying the project because no writes occur. These tie parameters to the surrounding workflow rather than restating types.

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 ('get a proposed fix for a specific bug in YOUR code') and positions it in the workflow as 'the fix step after find_bugs'. Explicitly distinguishes it from siblings prove_fix and find_bugs, and clarifies it authoring a diff rather than editing files.

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 ('after find_bugs'), the required next step ('Review the diff, then call prove_fix ... BEFORE applying it'), the gating condition ('Apply the patch only after inspecting that result'), and async handling ('Follow that SAME job ... never repeat this tool to poll'). 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 already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: the tool returns a next_tool_call to be followed iteratively, and a running response is explicitly not proof of success. It does not cover auth, rate limits, or return shape, but the added polling semantics are substantial.

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?

Front-loaded with the core action and resource, then the procedural rule. The final two sentences are somewhat aphoristic ('a proposed plan is not execution proof'), but they do carry the meaningful warning that only a completed verdict establishes a pass, so they earn most of their space.

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 polling tool with no output schema, the description supplies the essential loop behavior and the success/error termination condition. It is nearly complete, though it never describes what next_tool_call or the 'receipt' actually contain, leaving the agent to discover that at runtime.

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?

Only one parameter (job_id) with 100% schema description coverage ('Exact job_id returned by the original call'). The description reinforces that it must be the SAME job but adds no new syntax or format detail beyond the schema, so the baseline 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 specific verb (Retrieve) plus the exact resource (the SAME running job) and enumerates the originating tools whose jobs it polls (find_bugs, fix_bug, prove_fix, verify_behavior, validate_integration). An agent can immediately tell this apart from the starter tools that create those jobs.

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 ('Retrieve the SAME running ... job') and an explicit when-not ('Never restart the original tool to poll'), plus the operating loop ('Follow next_tool_call until status is done or error'). The anti-pattern is named directly, leaving nothing 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 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 only cover the safety quadruple (readOnly=false, openWorld=true, idempotent=false, destructive=false). The description adds substantial behavioral context beyond that: the account key used, no browser sign-in, secrets never appear in chat, return is limited to a private dotenv path and variable names, the file must never be read/printed/catted, existing production configuration must be preserved, and the file must be deleted after testing.

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 purpose and guardrails are front-loaded, but the body is a dense run-on of imperatives that partially repeats itself ('no secret values in chat' vs 'never cat/read/print it or paste values into a prompt'). Most content is safety-critical, so little is truly wasted, but the packaging hurts scanability.

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 multi-step credential-installation tool with no output schema, the description covers the full lifecycle: preconditions, env_mapping usage, twin base URL configuration, preflight/execute, receipt retrieval, and cleanup. Nothing an agent needs to invoke 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 only 33%, so the description must carry the load. It does well on env_mapping, giving the exact mapping semantics and an example ('FETCHSANDBOX_STRIPE_WEBHOOK_SECRET:STRIPE_WEBHOOK_SECRET') and noting unspecified names are preserved, but session_id and run_id are never explained beyond the surrounding workflow narrative.

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 precise verb and resource: install temporary twin API keys, webhook signing secrets and verifier token for an owned run configured by validate_integration. It names the sibling (validate_integration) and the operational scope (local coding agents only), so an agent can distinguish it from other workflow tools.

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 scopes who may use it ('Local coding agents only'), when to use it (after validate_integration configures an owned run), what to feed it (env_mapping from returned required_secret_names), and when NOT to use it (hosted Replit/Lovable use their protected browser handoff instead). This is a full when/when-not/alternative routing.

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 declare readOnly/idempotent/non-destructive, and the description goes beyond them: inspecting via workflow_name does not execute, default results are summaries only, output includes runnable failure scenarios, and cross-provider workflows must use the returned namespace rather than the provider slug. Auth requirements and any result limits/pagination are not mentioned, keeping it short of 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?

Purpose and the primary usage modes are front-loaded, and most sentences carry operational information. The closing sentences about choosing scenarios and asking about ambiguous business requirements drift toward agent procedure rather than tool behavior, making the block 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?

There is no output schema, so the description must describe returns, and it does: summaries by default, full definitions (request bodies, assertions, outcomes, invariants) when workflow_name is passed, plus the failure-scenario catalog with exact invocation instructions. For a zero-required-param, read-only listing tool this is complete enough to call 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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning: 'Known provider slugs need no import' tells the agent it can skip import_spec, and the cross-provider note clarifies that spec_slug must be replaced by the returned namespace in that case. The workflow_name explanation largely restates the schema text, which caps the score.

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 ('List the named, runnable workflows') and defines what a workflow is with a concrete example journey. It clarifies scope by noting it does not execute anything, but it never names or contrasts against the actual siblings (run_workflow, quickrun, validate_integration), so differentiation is implied rather than explicit.

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 conditions ('exploration' vs 'scoped validation before run_all_workflows') and a concrete sequencing recipe: list, filter by user intent, then pass matching ids as workflow_names. It also states the condition for the detail mode (pass an exact returned id/name) and warns not to guess scenario names.

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?

Despite annotations covering safety hints, the description adds substantial behavioral context that structured fields cannot: the deliberate 404 for browser/curl, that status only checks transport while validate_integration tests real connectivity, that a disconnect or backend restart ends the lease, and that the relay credential is internal and must never be exposed. These are exactly the operational traits an agent needs and are not derivable from 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?

This is a ~700-word playbook for a two-parameter tool, not a tool description. While the numbered steps (1)-(7) give some shape, large stretches (fixture read-back, replay edge cases, buggy-vs-fixed comparison) belong in workflow documentation, and the sheer volume obscures the front-loaded purpose.

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 orchestration tool with no output schema, the description is thorough: it names configuration fields (application_config.event_destinations, event_delivery), the execution/polling cycle, receipt retrieval, and cleanup. It is arguably over-complete, but nothing an agent needs to call the tool correctly appears 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 0% for both parameters, so the description carries the load. It does mention action=open with a port and distinguishes status ('checks only the transport') and close ('Close the tunnel'), covering the enum values implicitly, but it never explains port constraints (1024-65535), what open returns, or the exact effect of status/close, leaving gaps the schema cannot fill.

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 sentence states a specific verb+resource+goal: connect a real local disposable test app to the FetchSandbox verifier without ngrok or an account token. It contrasts with siblings like install_test_credentials and validate_integration implicitly, but the actual purpose is then buried under hundreds of words of workflow steps, so an agent must dig to extract it.

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?

Rich when/when-not guidance: 'Local stdio coding agents only; hosted builders use their published app origin,' the prove_fix fallback when local startup fails, and explicit warnings not to treat deliberate 404s as failed connectivity. Alternatives are named (validate_integration preflight, direct signed-event mode, hosted receipt suites), though they are tangled into numbered steps rather than stated as selection rules.

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?

Goes well beyond the annotations: long-running calls return status:running plus next_tool_call:get_job and must be followed rather than re-polled, prove_fix builds its own before/after copies and never writes to the caller's tree, paths outside the workspace are refused, and green only occurs on a measured flip. The readOnlyHint=false/destructiveHint=false pairing is consistent with the 'runs in its own sandbox copy, does not touch your tree' behavior.

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?

Front-loads the async-job handling rule, then the proof semantics, then the prohibitions, in a logical order. It is long and caps-heavy with some repetitive emphasis ('DO NOT SUBSTITUTE YOUR OWN TEST' restated in the following sentence), which costs a 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 complex, open-world, six-parameter tool with no output schema, the description covers the execution model, the diff-application flow, the receipt's provider-mode evidence scopes, the preconditions for an honest proof, and the async continuation rule. Nothing material to calling 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 the schema already documents all six parameters; baseline would be 3. The description nevertheless adds real meaning: the bug field carries the acceptance criteria and scope, diff is the fix_bug output, path must not be a copied project, and sandbox_id is usually omitted because the last twin is auto-attached.

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: it proves a fix by applying the diff to a copy and running the same failure probe before/after, emitting an own-code proof receipt. It is clearly distinguished from siblings like fix_bug (which writes the 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?

Explicit when-to-use: call before writing the fix to disk, with the still-buggy tree plus the diff. Explicit when-not and alternatives: do not substitute an agent-authored test, and call this anyway if one exists, because the two answer different questions.

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?

Goes well beyond the annotations by disclosing the side effect (it spins up the sandbox by slug, so no import_spec/sandbox_id is needed) and the return payload (sandbox_id + flow_run_id + receipt URL). It also draws a hard scope boundary: 'This does not execute or prove the caller's application.' It stops short of mentioning auth, cost, or sandbox lifetime, so it is strong but not exhaustive.

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?

Front-loaded with the action and its key advantage ('in ONE call'), then flows through prerequisites, reproduction, return values, and exclusions in a logical order. It is dense and slightly long, but nearly every sentence carries routing or behavioral 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?

Despite no output schema, the description names what is returned and what to do with it (pass both ids to verify_behavior), covers the prerequisite step (guide) and the alternative tool (run_workflow), and states the tool's scope limits. An agent has everything needed to select and 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%, so the baseline is 3. The description does add relational context (values come from guide's output) and a concrete scenario example, but the schema descriptions already state 'from guide', so the added value is marginal.

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 reference workflow against a KNOWN, bundled spec ... in ONE call') and immediately scopes it to bundled specs (stripe, clerk, descope, etc.). It explicitly distinguishes itself from sibling tools run_workflow, import_spec, find_bugs, fix_bug and prove_fix, so an agent can route without opening any 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 ordered flow ('call guide on their prompt, then call quickrun with the returned spec + workflow'), names the failure-repro path via guide's matched_bug_pattern.reproduce_with.scenario, and states the one condition under which run_workflow is the correct alternative (already holding a sandbox_id from import_spec). It also states when NOT to use it (proving a bug in the caller's own project).

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?

Beyond the annotations, the description discloses sign-in requirements, session/twin lifecycle, async non-blocking execution ('execute:true starts the existing backend job and returns running promptly'), credential installation via install_test_credentials, bounded observation windows, and strict cleanup obligations for temporary secrets. No behavioral claim conflicts with readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false.

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?

Roughly 2,500 words of undifferentiated prose with no headings or grouping, front-loaded with a 'Completion rule' block rather than the tool's purpose. Individual sentences are often operationally relevant, but the sheer size and lack of structure make it hard to scan and largely unregisterable by an agent in one pass.

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 16-parameter, deeply nested tool with no output schema, the description compensates thoroughly: it explains returned session_id/twin URLs/next_action, failure modes (configuration_rejected, setup_blocked, requirements_model_unavailable), suite options, and provider-specific lifecycle behavior. Nothing an agent needs to call it correctly appears 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 94%, so the baseline is 3, but the description adds real orchestration meaning: 'Call once with providers, then follow the returned next_action,' 'Do not include application_context in the initial session call,' and the arm→probe→run_id sequencing. It clarifies how session_id/run_id/app_base_url relate rather than restating 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 operative sentence — 'Start a validation session for the user's integration... hands back a FRESH twin per provider and asks the user to point their app at it, then reads external provider traffic' — is a specific verb+resource and explicitly distinguishes the tool from quickrun/run_workflow. However, the description opens with 'Completion rule: a request to verify an app includes its applicable failure checks...' rather than the purpose, so an agent must dig to find what the tool actually 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?

Named alternatives and exclusions are explicit: 'Do not substitute guide, quickrun, list_workflows, or reference probes for application verification,' 'Use it when someone wants their integration verified before launch,' 'Never execute while host-side setup is pending.' Conditions selecting the arm/probe path vs the hosted suite path are also spelled out.

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.