Snapback

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds real context: results are token-scoped to the calling agent, the tool is free, and the return payload format is illustrated. These are not derivable from the annotations or schema.

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 core payload (what it returns and when to call it) is front-loaded and every sentence is informative. Slight slack from the capitalized emphasis, the inline example, and the trailing 'Free.', but nothing is genuinely wasted.

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 zero-required-parameter read tool with an output schema, the definition covers scoping, timing, cost, and result shape adequately. The only gap is that it duplicates return-value detail the output schema already carries rather than adding more.

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 single optional 'limit' parameter has 100% schema description coverage including its default of 5, so the schema fully documents it. The description adds no syntax or format guidance for limit, which is the expected baseline when the schema does all the work.

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: returns this agent's recurring failure patterns from past diagnoses, with the exact shape of the result (failure classes, counts, percentage shares) and a concrete example. It is clearly distinguishable from siblings like my_impact and my_usage.

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 says 'Call it before a run to know what to guard against,' giving a concrete usage moment. It does not name a competing sibling or state when NOT to use it, so it falls short of the 5 tier.

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 establish readOnly, idempotent, non-destructive, closed-world behavior. The description adds important context beyond annotations: it is advisory only and never blocks, runs mid-run without LLM latency, accepts whatever counters are available, and returns suggested_actions plus projected cost of not acting.

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 core purpose, then output behavior, usage cadence, advisory nature, and a compact parameter list. Every sentence is useful and the description is appropriately sized.

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?

An output schema exists, so return values need not be explained. However, with 11 parameters and very low schema description coverage, the description leaves several inputs semantically unclear, especially task and recent_actions. It is adequate for knowing when to call the tool but not fully complete for invoking it with confidence.

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 only 9%, so the description should compensate. It lists 8 of 11 parameter names but gives no semantics, units, or usage guidance for them, and omits task, format, and recent_actions entirely. The phrase 'send whatever counters you have' implies optionality but adds little meaning beyond 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?

States a specific verb and resource: live MID-RUN budget check, advisory only, fast/no LLM. It is clear what the tool does, but it does not explicitly differentiate itself from related siblings such as suggest_budget_recovery or preflight.

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 clear usage context: call it every few steps to catch a runaway before hitting a limit. It does not name alternatives or state when not to use it, but the intended cadence and purpose are explicit.

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/closed-world, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it is deterministic ('no LLM', 'no token', 'free') and it explains how it interprets retried/action fields, which an agent can't 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 front-loaded, followed by a clarifying example, then the input shape and the cost characteristic. Nearly every sentence earns its place; the tagline about cost is compact and informative 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 an output schema present, return values need no explanation, and annotations cover the safety profile. The description supplies enough context (ordering, item shape, determinism, worked example) for correct invocation, missing only explicit sibling routing.

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% and there is a single parameter, so the schema already documents the ordering and the string-or-object shape. The description restates 'string or {error, retried, action}' without adding format or constraint detail, so 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 (find) and resource (the TRUE root among an ordered error list) with a concrete 429->401 example that pins down exactly what it computes. It doesn't explicitly name or contrast against siblings like diagnose_trace, but the operation is unambiguous enough that an agent knows it's a deterministic root-finder.

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 phrase 'Given an ORDERED list of errors from a run (oldest first)' establishes the input context and implies when to reach for it ('not just the final symptom you see'). However, it never names an alternative (e.g. diagnose_trace) or states when this tool is the wrong choice, leaving routing 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 non-destructive, so the safety profile is covered. The description adds value beyond them: it discloses cost ('Free, no token') and the accepted input shapes, which the agent needs to know to trust and shape the call.

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 purpose, then the input contract, then the return value, all in two dense sentences with no filler. The long parenthetical of accepted formats is information-rich but slightly heavy on a single read.

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?

An output schema exists so return values needn't be detailed, yet the description still flags the return shape and its downstream use. Combined with the cost note and accepted-format list, an agent has everything needed to invoke this 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, but the description goes further by detailing what 'source' accepts — a bare list, or an object wrapping spans/steps/messages/events/logs, including OTel spans, OpenAI/LangChain messages, and generic {tool,input,output} arrays. The optional 'hint' parameter is only covered by the schema, but the core parameter is well enriched.

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 (convert) and resource (raw logs → Snapback trace) and clarifies the outcome: a JSON trace the user doesn't have to hand-craft. It also routes the agent forward by naming diagnose_trace as the consumer, which cleanly separates it from that sibling.

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

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

Gives clear context for use — 'so you don't hand-craft JSON' and 'ready to pass straight to diagnose_trace' — and enumerates which input formats qualify. It stops short of stating when NOT to use it (e.g., when logs are already a trace), so it is strong but not fully explicit.

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 behavior. The description adds useful behavioral context beyond them: it is 'fast, no LLM, free' and returns 'non-blocking advice, not a verdict,' which tells the agent how to interpret the output.

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 tight sentences with the mid-run timing and purpose front-loaded. Each sentence earns its place by covering purpose, timing, and output nature without repetition.

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 an output schema present, the description does not need to detail return values, and it still summarizes what comes back. It gives enough context for an agent to call the tool correctly during a run.

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 both parameters — steps as recent action/tool records and threshold as the repeat count. The description does not add syntax or default details beyond what the schema provides, making the baseline 3 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 — a mid-run loop check — and explains exactly what it returns: whether the agent is stuck repeating a tool call plus a concrete next move. It distinguishes itself from postmortem diagnostics by emphasizing 'MID-RUN' and 'don't wait for a postmortem.'

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 says when to call it: 'every few steps' and 'BEFORE you burn your step budget,' with a clear when-not: 'don't wait for a postmortem.' It references diagnose_trace only for step shape, not as an explicit alternative, so routing guidance is clear but not fully enumerated.

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 (readOnly, idempotent, non-destructive), yet the description still adds substantial behavior: the 20-trace cap, per-trace metering equivalent to separate diagnose_trace calls, order-preserving verdicts array, and failure isolation of a bad trace. Those cost and error-isolation semantics are exactly what an agent needs and are not in 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?

Three dense sentences, front-loaded with the batch/limit defining facts, then cost, then return/isolation behavior. No filler or restatement of the name.

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?

An output schema exists, so return values needn't be spelled out, yet the description still notes the verdicts array ordering. Combined with cost and error-isolation disclosure, an agent has everything needed to invoke this batch tool correctly.

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

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

Schema coverage is 100% and there is only one parameter, so the schema already documents the traces array. The description reinforces the 'max 20' cap and 'trace objects' shape but adds no format or structure detail beyond that, matching the baseline for fully covered schemas.

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?

Specific verb (diagnose) plus resource (multiple traces) with an explicit upper bound of 20. It cleanly differentiates itself from the sibling diagnose_trace by calling out batch scope and per-trace results.

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?

States the intended scenario ('post-run analysis of many failures at once') and names the alternative ('instead of N round-trips'), which implicitly routes the agent away from repeated diagnose_trace calls. It stops short of an explicit when-not-to-use rule, such as single-trace or interactive use.

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?

Adds substantial behavior beyond the annotations: instant library lookup with no LLM, free/no-token, and an explicit GATE CONTRACT (auto-apply only when confidence>=0.85 AND source=='library' AND auto_safe==true; never auto-apply mutate/destructive fixes). This safety gate is exactly the kind of context annotations cannot express, and it is consistent with readOnlyHint/non-destructive.

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 front-loaded in the first clause, and the gate contract earns its space. However, it is delivered as one dense run-on with semicolons and em-dashes, and the return-field list duplicates the existing output schema, so it is 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?

Given an output schema, rich annotations, and 100% schema coverage, the description fills the remaining gaps: trigger conditions, the auto-apply gate verdict (gate.auto_apply_ok), and the no-LLM/library provenance of results. An agent has everything needed to call it and act on the verdict.

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% across all 4 params, so the schema already documents error, action, format, and context. The description reinforces 'pass the error text (and optional context)' but adds no syntax, format, or constraint detail beyond what the schema provides; 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 (diagnose) and an enumerated resource scope: payments (x402/EIP-3009), Solana on-chain, MCP protocol, RPC/providers, wallets. The domain enumeration and 'library of VERIFIED fixes' framing let an agent distinguish this single-error diagnostician from siblings like diagnose_batch and diagnose_trace 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?

Explicit triggers are given: 'Use it the moment you hit a transaction_simulation_failed, BlockhashNotFound, a -32xxx RPC code, 4001/-32002 wallet error, an attestation failure, or any infra error you can't instantly resolve.' That is a clear when-to-use context, but no sibling alternative is named (e.g. when to prefer diagnose_trace or search_docs), so it falls short of a full 5.

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 (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: a fast path for known patterns (<1s) versus a ~25s LLM-backed path for novel failures, plus timeout and async-calling advice. That latency divergence is exactly the kind of behavior an agent must know to call this 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?

Front-loaded with purpose and return shape, then a clearly labeled LATENCY paragraph. Every sentence earns its place, including the operational timeout/async warning, and nothing is redundant.

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 an output schema present, the description need not explain return values, yet it still summarizes the verdict fields for fast orientation. The only input is a nested trace object covered by the schema, and the latency/async behavior is fully disclosed, leaving no gap an agent needs filled.

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 a single 'trace' parameter, so the schema carries parameter meaning. The description adds no syntax, format, or shape detail for the trace object beyond what the schema states, which is the baseline-3 case for a fully-covered 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?

States a specific verb and resource ('Diagnose why an AI agent run failed') and names the exact output shape (failure_class, failed_at_step, root_cause, fix_suggestion, confidence). An agent can distinguish this from siblings like diagnose_batch or diagnose_infra_error, which operate on different scopes.

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 clear context (a failed agent run) and explicit operational guidance: set client timeout to 30s and don't block the agent loop. It does not explicitly distinguish this single-trace tool from the batch or infra-error diagnosis siblings, so routing among those 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, openWorldHint=false, and destructiveHint=false. The description adds useful context beyond those fields: it lists the possible returned statuses (pending/approved/rejected/in_library) and states the operation is free and needs no token, with no 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?

Two compact sentences front-load the action and source, then efficiently list statuses and the no-cost/no-token constraint. Every phrase earns its place with no redundancy.

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 read-only status check with annotations covering safety and an output schema covering return shape, the description supplies the missing essentials: where request_id comes from, possible statuses, and cost. Minor gaps around invalid-id behavior remain but are not critical.

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 single request_id parameter has 0% schema description coverage, so the description must compensate. It identifies the source of the id (request_pattern's request_id) but does not specify a format, example, or type detail, leaving meaningful gaps.

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 ('Check what happened') and resource ('a pattern you requested'), and names the originating tool request_pattern, so it is distinguishable from siblings like request_pattern. The scope is clear and actionable.

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?

Tells the agent to use it with a request_id from request_pattern's request_id, giving clear context for the trigger. It does not list exclusions or alternatives among sibling status/diagnostic tools, but the when-to-use condition is explicit.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds a genuinely non-annotated constraint, 'your org only', which tells the agent about tenant scoping, but it says nothing about behavior when the id is unknown or not in the org.

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

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

A single front-loaded sentence with no filler. Slightly compressed to the point of ambiguity ('its id' refers to an unstated antecedent), but structurally efficient.

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?

An output schema exists, so return values need no explanation. However, with zero required parameters and no param documentation, the description leaves open whether verdict_id, trace_id, or either is needed to call it correctly, which is a real gap for a lookup 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 0% for both parameters, so the description carries the full burden. It only restates the parameter names ('by its id or by trace_id') without format, precedence when both are supplied, or what happens if neither is given (both are optional in 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?

Clear verb (fetch) plus resource (verdict) and states the two lookup keys, id or trace_id. It does not distinguish itself from trace-related siblings like diagnose_trace or convert_trace, so it falls short of a 5.

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?

'Previously produced verdict' implies the record must already exist, but there is no explicit when-to-use, no mention of what to do when no verdict exists, and no named alternative. Usage is only implied.

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 the safety profile is covered. The description adds one genuinely new behavioral fact — 'Token-scoped to you' — which clarifies auth/identity scoping, but the rest restates what the output schema will return.

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 verb and the metric list, which is the useful part. The closing sentence 'Turns your input into visible collaboration' is mild marketing filler that adds no callable information.

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

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

For a parameterless read-only stats tool with an output schema, the description covers purpose, scope, and identity binding. Since the output schema documents the return shape, nothing essential 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?

Zero parameters, so there is no parameter semantics to document; the schema coverage figure is vacuous. Baseline 4 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 and resource ('See how your feedback + pattern requests have shaped the shared library') and enumerates the concrete metrics returned. It implicitly distinguishes itself from what_others_did by noting the scope is your own contributions, but it never names the potentially confusable sibling my_usage.

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 implies when you'd want this (to review your contribution history) but gives no explicit when-to-use, prerequisites, or alternatives to my_usage/what_others_did. Usage is inferable rather than stated.

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, closed-world. The description adds useful non-structured context: it is token-scoped (per-caller visibility) and free (no cost impact). It does not discuss caching, rate limits, or freshness of the figures, 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?

One front-loaded sentence covering what it returns, followed by a short usage cue and a scope/cost tag. Every clause earns its place; no 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?

Output schema exists, so return structure is already defined, yet the description's enumeration of metrics gives an agent enough to decide relevance. Combined with annotations and the token-scoped/free note, nothing needed 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?

The tool takes zero parameters, so there is no schema semantics to compensate for; the baseline for a 0-param tool applies. The description correctly avoids inventing parameter language.

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 resource ('YOUR current usage + remaining allowance') and enumerates the concrete contents (snapbacks, guard checks, spend, % used, reset time). An agent can distinguish this from siblings like budget_guard or my_impact 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?

Explicitly advises 'Call it periodically to avoid surprises' and frames the purpose as self-governing spend, which is clear context. It stops short of naming an alternative tool or stating when-not to use it, so it misses the top bar.

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 meaningful non-structured context: results come from Snapback's library, are ranked, and carry failure_class/root_cause/fix_suggestion, and the tool is meant as a self-correction step before execution.

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 short sentences, front-loaded with the 'BEFORE running' constraint in caps, which is exactly the operative signal. Minor redundancy between 'BEFORE running' and 'Call this before executing a plan', which keeps it from a 5.

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?

An output schema exists, so return values need not be re-explained; with all parameters optional and fully documented, the agent has enough to invoke it. The only gap is the absence of any explicit sibling routing for post-hoc failure diagnosis.

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% — tags, limit, and agent_stack are all documented in the schema with examples and defaults. The description adds nothing about how a 'given agent setup' maps to these parameters, 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 concrete verb and resource ('get known failure patterns for a given agent setup') plus the returned shape, so the agent knows exactly what it gets. It implies differentiation from the diagnose_* siblings via 'BEFORE running' (preventive vs. post-hoc), but never names a sibling or draws the contrast explicitly, so it falls short of a 5.

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 clear timing guidance: 'Call this before executing a plan and self-correct.' This tells the agent when the tool belongs in a workflow. There is no statement of when NOT to use it or which sibling to prefer for post-hoc diagnosis, so it is context-rich but not exclusionary.

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 (readOnly/idempotent/destructive=false), it discloses that the tool is free, requires no token, uses no LLM, makes no network calls, and reads only caller-supplied data — exactly the operational context an agent needs before wiring it into a retry loop. Note the mild tension with openWorldHint=true, but it is not a contradiction of any hint.

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 decision question, then the inputs, then the payoff, then the operational caveats — four tight sentences with no filler. The one long sentence carries the cost-saving rationale and is worth its length.

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?

An output schema exists so return values need no explanation, and the description still characterizes the return as 'deterministic routing advice with the reason'. For a read-only, one-required-param advisory tool, 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 already 100%, so the baseline is 3; the description adds real semantic value by grouping the five params into two orthogonal topologies (current_chain/available_chains vs. current_provider/available_providers) and signaling they are combinable via 'and/or'. It does not, however, explain how the tool behaves when only one side of the topology is supplied.

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 the exact decision it resolves (retry / switch / fall back / stop) and names the resource: deterministic failover routing advice from an error plus a topology. It is clearly distinguishable from sibling diagnose_* tools by being a deterministic, no-LLM router rather than a diagnostic.

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 states the triggering context (you hit an error and are deciding whether to retry or switch) and the inputs to supply, with a concrete motivating example (flaky Solana RPC retried 5x instead of switching to Base). It doesn't name alternative siblings or say when NOT to use this, so it stops short of a 5.

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 write/non-idempotent/open-world, and the description adds meaningful context beyond them: token-scoped identity ('so we know it's your org'), free of cost, and the fact that the data feeds a shared crowd view. It doesn't restate idempotency or return behavior, but the added auth/cost/crowd framing is genuine value.

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, then the caller/trigger, then the rationale. The 'TWO purposes' sentence is a bit expansive but each clause carries information the agent cannot get from structured fields, so it largely earns its length.

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 an output schema present, return values need not be described, and the description covers identity scoping, cost, trigger, and dual purpose. The main gap is not steering the agent toward fix_id for per-fix crowd evidence, which is the key behavioral nuance of this 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 57%, and the description names the parameters to pass while clarifying 'succeeded (did the retry work?)'. It leaves failure_class, family, and confidence unexplained, and notably omits the recommended fix_id, whose per-fix crowd-evidence role is documented only in 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?

States a specific verb+resource ('Report the outcome of an auto-applied fix') and identifies the caller (the self-heal interceptor) and the trigger (after it gate-applied a fix and retried). It also implicitly distinguishes itself from the sibling what_others_did, which it describes as the consumer of this data.

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?

Explains the context in which reporting happens (post gate-applied fix + retry) and the two downstream uses of the data, which tells the agent why to submit. It does not state explicitly when an agent should call it manually vs. leaving it to the interceptor, so it falls short of full when/when-not guidance.

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 the safety profile (readOnly false, destructive false, openWorld true, non-idempotent), so the description's job is to add what they cannot say. It does: the message 'goes straight to our roadmap/backlog', context is 'redacted server-side', and it is 'Free — no token needed', which is important budget context given the sibling budget_guard/my_usage tools.

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, front-loaded with the core action followed by the trigger conditions and the cost/side-effect note. Every sentence earns its place; slight redundancy between the first and second sentences keeps it from a 5.

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?

An output schema exists, so return values need not be described, and all four params are documented. The description supplies the missing behavioural context (routing destination, redaction, no token cost), leaving only the sibling-overlap with submit_feedback unaddressed.

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 kind, context, message and verdict_id; the baseline is 3. The description adds only marginal param-level value ('be specific', server-side redaction of context) beyond what the schema states.

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 concrete verb+resource: 'ask us to add a failure pattern to the library, or report a problem we couldn't diagnose well.' It is clearly not diagnose_trace (which analyses) and not report_outcome. However, it never distinguishes itself from the sibling submit_feedback, which sounds like a near-overlapping channel, so an agent cannot fully disambiguate on purpose alone.

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 trigger conditions: 'when diagnose_trace didn't have a good answer, when you keep hitting a failure we don't classify, or when you want a specific kind of problem supported.' Strong usage context, but no 'when not to use' and no routing away from submit_feedback.

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/openWorld/idempotent/non-destructive, so the bar is lower, but the description still adds real operational context: 'Free and needs no token,' which tells the agent there is no auth or cost barrier to calling it freely.

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 front-loaded and the single dash-list packs useful scope without fluff; the closing call-to-action is actionable. The middle clause runs slightly long but every phrase carries 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?

An output schema exists so return shape needn't be documented, and annotations cover the safety profile. Purpose, coverage, cost, and invocation timing are all present; only the limit parameter's behavior is left entirely to the schema.

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

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

Schema description coverage is 100% and the description's example ('how to format a trace') mirrors the query param's schema example, adding no new semantics. No mention of the limit parameter. Baseline 3 per the intact-schema rule.

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 ('Search Snapback's documentation') and enumerates the topics covered (trace formatting, tool behavior, failure taxonomy, auth, pricing, errors), which cleanly separates it from every operational sibling like diagnose_trace or get_verdict.

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 routes the agent: 'Call this first if you're unsure how to format a request or what a verdict means.' The trigger condition is clear, though it never states when not to bother (e.g., once familiar) since there is no competing doc-lookup alternative.

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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description adds real context beyond them: it states the session is freed/consumed by the call and that it is free with no token cost, which an agent cannot derive from structured fields.

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

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

Two short, front-loaded sentences with zero filler; the primary effect (closing the session) precedes secondary details (summary, cost).

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 one-parameter lifecycle tool with annotations covering safety and an output schema covering returns, the description supplies everything needed to call it correctly, including the cost cue. Only the input parameter's identity/format is left undocumented.

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 0% and the description never mentions session_id, so it adds no semantics beyond the schema. The single parameter is self-explanatory by name, keeping this at the 'adequate' baseline rather than failing.

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 ('Close a live session') plus the outcome ('get a short run summary'). It is clearly distinguishable from session_start/session_step by the 'close' verb, though it does not name them explicitly.

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

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

Usage is only implied: 'Close a live session' suggests calling this when work on a session is finished, but there is no explicit when-to-use, prerequisite, or alternative guidance relative to session_step or session_start.

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?

Adds real value beyond annotations by disclosing that it returns a session_id, that it is free (no token), and that this is 'always-on guardian mode' with real-time warnings. Annotations cover readOnly/destructive/idempotent hints, but the description goes further with cost and return-value context. Could say more about session lifetime or limits, hence not 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?

Front-loaded with the core action, then the value proposition, then the return value, then the companion-tool workflow. Every clause earns its place; no 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?

For a session-lifecycle entry point, the description covers purpose, return value, cost, and sibling coordination. Output schema exists so return format needn't be fully explained. Minor gaps: no mention of session lifetime, concurrency, or failure modes.

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 optional parameter (agent_id) and schema description coverage is 100%, so the schema already carries the semantics. The description adds no param-specific detail. 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+resource ('Open a LIVE mid-run session') and immediately explains what the session does: real-time step-by-step watching and warnings for loop/token/cost/context. Clearly distinguishable from siblings like session_step and session_end, whose roles are also named.

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 tells the agent the full workflow: call session_start to open, session_step as you run, and session_end when done. This is a complete lifecycle guide that routes usage across three sibling tools without ambiguity.

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 readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the agent knows it is a non-destructive write. The description adds real value beyond that: warnings are advisory and immediate, and it is free. But it never says what is persisted or whether a session must exist, so behavioral coverage is partial.

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 and mostly tight, but the parenthetical counter list is dumped in and the trailing 'context_window. context_window' is a duplicated, garbled fragment that hurts readability. The core message lands in the first sentence.

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?

An output schema exists, so return values need not be described, and the description correctly focuses on inputs, timing, and advisory semantics. The only real gap is silence on session_id and session lifecycle (session_start prerequisite), which an agent must infer from the schema's required field.

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 75%, and the description goes further by enumerating the counter keys (step, max_steps, tokens_used, token_budget, cost_used_usd, cost_budget_usd, context_used, context_window, task, recent_actions) that the schema only summarizes as 'tokens/cost/context/max_steps'. session_id and loop_threshold are left to the schema, which documents them adequately.

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: 'Report ONE step of a live run and get back any warnings immediately (loop detected / budget breach).' An agent can tell it reports step telemetry, distinct from pure analysis tools. It does not explicitly differentiate itself from siblings like detect_loop or budget_guard, which overlap in function.

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?

Implies usage during a live run and says warnings 'are advisory - act on them to self-correct mid-run,' which is useful timing guidance. However, it never states when to prefer this over detect_loop/budget_guard, nor any prerequisites (e.g., must call session_start first). Usage is implied rather than laid 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 only declare the safety profile (readOnly=false, idempotent=false, openWorld=true); the description adds the substantive consequences: it mutates a SHARED pattern library, ratings reweight future verdicts, and trace content is never shared while patterns are anonymized. That privacy and side-effect disclosure is exactly what annotations cannot convey.

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 the when-to-call rule, and each sentence carries distinct information (semantics, timing, shared-library effect, alternative). It is dense with em-dashes and parentheticals, but nothing is wasted.

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?

An output schema exists, so return values need no explanation, and annotations plus the description together cover safety, side effects, and data-sharing policy. For a 3-param feedback tool, 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% and already documents verdict_id, correct, and note. The description's parameter info ('correct=true/false', note = 'did the fix work? what was wrong?') largely restates the schema, adding only framing rather than new syntax or constraints. 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 and object ('Tell Snapback whether a verdict was correct') plus the payload shape (correct flag + optional note). It explicitly distinguishes itself from request_pattern, which covers the adjacent 'new pattern / unsolved problem' case.

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 timing ('call it AFTER you act on a verdict and see the outcome'), a cardinality constraint ('ONE rating per verdict'), and names the alternative tool (request_pattern) with the condition that selects it. 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds meaningful traits beyond them: free, no token spend, no LLM call, and that output is a ranked trade-off rather than a single answer. It does not describe ordering tie-breaks, but the additions are substantive.

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 triggering condition and the ranked output format using compact enumeration. The marketing-style closer ('Turns budget_guard's...') earns its place as sibling routing, though the piece is slightly denser than needed.

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?

An output schema exists, so return-value explanation is not required, and the description does convey the shape of the ranking. However, for a 7-parameter tool with no schema descriptions, the lack of per-parameter semantics leaves a real gap 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?

Seven parameters with 0% schema description coverage, and the description only gestures at 'your counters' via the phrase token/context/cost budget. It never clarifies the distinction between tokens_used and context_used, the units of the budgets, or what recent_actions should contain, so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource (suggest budget recovery) and enumerates the exact output: four ranked recovery options scored by speed gained, accuracy lost, and cost saved. It also explicitly positions itself against the sibling budget_guard, so an agent can tell the two apart 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?

Triggers the tool with a clear condition (approaching a token/context/cost budget mid-run) and routes relative to budget_guard, which merely warns. It lacks explicit when-not-to-use guidance, but the mid-run budget context is 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial context beyond them: it's free/no-token, anonymized and aggregated, privacy-safe (never exposes org/agent/trace identity), and suppressed below a min-sample threshold. That is exactly the kind of behavioral disclosure annotations cannot provide.

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

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

Front-loads the purpose and the return shape, and every sentence is mostly functional. The closing 'This is the network effect…' line is promotional filler rather than operational guidance, costing 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?

An output schema exists so the return fields needn't be re-explained, and the description still lists them (mildly redundant). Combined with full param coverage and rich behavioral notes, the definition is complete enough for an agent to call it correctly; the only gap is the absence of an explicit alternative-tool routing statement.

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% and both params are documented, so baseline is 3. The description adds real value by explaining that failure_class and error are alternative inputs and that passing error triggers a diagnostic mapping step, plus naming example failure_class values. That goes beyond what the schema states, though it doesn't fully enumerate the mapping behavior.

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: look up what OTHER agents did about a given failure_class and whether it worked. This is clearly distinguishable from siblings like get_verdict, search_docs, and diagnose_trace because it emphasizes anonymized cross-agent aggregation.

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 a clear triggering condition — use it when you hit a failure and want the crowd's verdict rather than 'the single library answer' — which implicitly contrasts with the single-source sibling tools. It stops short of naming a specific alternative tool or stating when not to use it, so it falls short of 5.

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