Snapback

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

No annotations are provided, so the description carries the full burden. It clearly indicates the tool is a read-only introspection call, gives a concrete return shape with an example, and discloses both token-scoping and that it is free. It could add data freshness or update behavior, but the essentials are covered.

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. The first sentence explains what it does and what result to expect, and the second gives when to use it and key constraints. Every sentence earns its place with 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 tool with one optional parameter and no output schema, the description is complete: it gives a return-format example, confirms scope to the calling agent, notes it is free, and states exactly when to call it. Nothing needed for 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%: the single 'limit' parameter is already documented as 'top N patterns (default 5)'. The tool description adds no additional parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('See what YOU tend to fail on') and names a concrete resource: your own recurring failure patterns across past diagnoses. It distinguishes itself from the sibling 'what_others_did' by emphasizing 'Token-scoped to your own agent,' so an agent can tell it 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?

The description explicitly says to 'Call it before a run to know what to guard against,' which gives clear timing and purpose. It does not mention when not to use it or name alternatives, so it falls just short of full exclusionary 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?

With no annotations provided, the description carries the full disclosure burden. It clearly states the tool is fast, does not invoke an LLM, is advisory only, and never blocks, which is valuable transparency about side effects and execution behavior. It could mention persistence or output details, but the core behavioral nature is well conveyed.

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 front-loaded with the core value proposition, then gives a clear call cadence, an important behavioral guarantee, and a parameter list. Every sentence earns its place and there is no filler or 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?

The description covers the tool's purpose, advisory nature, and usage cadence, which is enough for basic invocation. However, it does not explain the full set of parameters, the output structure, or how missing counters are handled, and there is no output schema to fill that gap.

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 must compensate. It merely lists parameter names like step, max_steps, tokens_used, and cost_budget_usd without explaining their meaning, units, or relationships to the computed metrics. It also omits task, format, and recent_actions, leaving significant ambiguity for an agent deciding what to pass.

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 performs a live mid-run budget check, returning advisory information on context, token, cost, step, and drift metrics. It does not explicitly name sibling tools, but the 'MID-RUN' and 'advisory only' framing helps distinguish it from preflight checks or recovery suggestions.

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 explicitly tells the agent when to call it: 'every few steps' during a run, to catch runaway behavior before hitting a limit. It does not explicitly state when not to use it or name alternatives, 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?

With no annotations, the description carries the behavioral burden and does a solid job: it explains the ordering requirement, handling of retried/cascaded errors, accepted element shapes (string or object with error/retried/action), and even notes no token or LLM usage. It does not specify the return format, but the core behavior is well disclosed.

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 with the main purpose. Every sentence earns its place: the core goal, a clarifying example, accepted input shapes, and the cost/behavior note. No filler or redundant restatement of the tool 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?

The description covers the input requirements, core logic, and constraints for a single-parameter tool. The main gap is not describing the exact return value or output format, which would be more important if there were no output schema, but the task is simple enough that the intent is largely inferable.

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

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

The schema already describes the errors parameter at 100% coverage, so the baseline is 3. The description adds meaningful semantics beyond the schema by specifying 'ordered list (oldest first)' and clarifying element variants, which improves an agent's ability to construct valid input.

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: 'find the TRUE root' from an ordered list of errors. It clarifies the intended behavior with a concrete example (429 retried causing a 401) and explicitly contrasts with 'the final symptom,' making it easy to distinguish from sibling diagnostic 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 clearly states when to use the tool: when you have an ordered list of errors from a run, oldest first. It also gives an exclusion by saying it finds the root rather than the final symptom, but it does not explicitly name alternative sibling tools or list conditions when not to use 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?

With no annotations provided, the description carries the full burden, and it does well: it discloses accepted input shapes (list vs. object with spans/steps/messages arrays), enumerates supported formats (OTel, OpenAI/LangChain, generic arrays), specifies the {trace} output, and even discloses cost behavior ('Free, no token'). It omits failure/validation behavior, but for a non-destructive transform this is solid coverage.

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, all front-loaded with the core purpose first, and every sentence earns its place: purpose/benefit, parameter format details, then output and cost signal. The parenthetical format list is dense but compact and directly actionable.

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

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

Despite having no output schema and no annotations, the description compensates by specifying the return shape ({trace}) and its intended consumer. For moderate complexity (multi-format input handling), it covers inputs, output, and cost. It only lacks failure-mode and size-limit guidance, which keeps it from a 5.

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 value beyond the schema: it expands 'source' by enumerating concrete supported formats (OTel spans, OpenAI/LangChain message lists, {tool,input,output} arrays) and clarifies that the object form may wrap spans/steps/messages/events/logs arrays. This meaningfully reduces an agent's guesswork about what inputs are valid.

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

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

The description opens with a specific verb+resource pair ('Turn your raw logs into a Snapback trace') that immediately distinguishes it from siblings like diagnose_trace and detect_loop. It also names its downstream consumer (diagnose_trace), cementing its unique role in the workflow.

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 'so you don't hand-craft JSON' gives clear when-to-use context, and the 'ready to pass straight to diagnose_trace' line signals the expected workflow. However, it never explicitly names alternatives or states when not to use this tool, so it stops short of full exclusions.

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

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

With no annotations, the description carries the full burden. It discloses that the tool is non-blocking, returns advice rather than a verdict, and is fast/free. It also clarifies the input expectation (recent steps) and the output type (whether stuck and a concrete next move). It doesn't detail rate limits or exact response format, but the key behavioral traits are covered.

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 with the key value proposition ('MID-RUN loop check (fast, no LLM, free)'). Every sentence earns its place: what it does, when to call it, and what it returns. No fluff.

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 2 params, 100% schema coverage, and no output schema, the description is quite complete. It explains the input shape, the timing, and the nature of the output. It could mention whether the output includes a suggested next action in a structured format, but the description already says 'get back whether you're stuck repeating a tool call and a concrete next move,' which is sufficient for an agent to decide to call it.

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. The description adds meaning by explaining the steps parameter expects 'recent steps (last ~5-10)' and references the same shape as diagnose_trace, which helps the agent understand what to pass. The threshold parameter is already well-described in the schema, but the description's context about 'identical consecutive calls' reinforces its semantics.

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's purpose: a mid-run loop check that detects whether the agent is stuck repeating a tool call and provides a concrete next move. It distinguishes itself from siblings like diagnose_trace by emphasizing it is fast, free, and meant to be called during a run, not as 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?

The description explicitly says when to use it: 'Send your recent steps DURING a run' and 'Call this every few steps to catch a loop BEFORE you burn your step budget.' It also contrasts with the alternative 'don't wait for a postmortem,' which implies diagnose_trace is for after-the-fact analysis. This is strong usage 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?

With no annotations, the description carries the full burden and delivers: it discloses that each trace is metered separately, that the return is a verdicts array with preserved order, and that a bad trace is isolated without failing the batch. This is valuable behavioral context beyond the raw 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?

Two sentences deliver the use case, capacity, metering, return shape, and failure isolation with zero filler. Information is front-loaded and every clause earns its place.

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

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

For a single-parameter tool with no output schema, the description covers return format, error isolation, capacity, and usage context. The schema documents the parameter, and 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?

The schema provides 100% coverage for the only parameter ('array of trace objects (max 20)'). The description repeats the 20-trace limit and adds output behavior (order preservation) but not much new input-side semantics, so the baseline 3 for high schema coverage 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'), a resource ('SEVERAL traces'), and a capacity limit ('up to 20'). It distinguishes itself from the sibling diagnose_trace by explicitly being the batch variant, and it mentions the per-trace metering tie to 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?

Explicitly tells when to use it: 'Use for post-run analysis of many failures at once instead of N round-trips.' This names the alternative behavior (N individual calls) and references diagnose_trace for meter semantics, giving clear routing 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?

With no annotations, the description carries the full burden. It discloses why the tool is free ('from the library (no LLM)'), the deterministic behavior ('instantly from the library'), and the auto-apply safety gate (confidence>=0.85, source=='library', auto_safe==true, and action_class restrictions). It does not mention error handling or timeouts, but the key safety behaviors are well covered, going beyond what annotations would have provided. It emphasizes that 'NEVER auto-apply a mutate or destructive fix', which is transparent about its own limits.

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 slightly long but dense with value. It front-loads the purpose, then provides detailed gate contract and usage triggers. The gate contract is wordy but necessary for safety. Every sentence adds either scope, safety, or usage nuance, so it earns its length, but could be trimmed. A 4 because it is well-structured and clear, with minor redundancy in the gate contract explanation.

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

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

The description is comprehensive: covers error types, return structure, free behavior, safety gate, and when to use. With 4 parameters (1 required) and no output schema, the description fully compensates by listing output fields and gate logic. The only gap is not specifying whether the tool handles unexpected error patterns gracefully or what happens if no match, but given the source is a library, that is implied. Extensive context for a diagnosing tool with high complexity.

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 has 100% coverage, with each parameter self-describing (e.g., error as 'exact error text', action as 'tool/operation that failed', format with enum and explanation, context as 'what you were doing'). The description adds a bit by giving examples of errors and the return fields, but it does not introduce new parameter-specific details beyond the schema. Baseline 3 is appropriate because the schema is complete; description adds marginal value in examples but not critical.

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 diagnoses 'cribic AGENT-INFRASTRUCTURE errors' across specific categories (payments, Solana, MCP, RPC, wallets) and returns structured fields (matched, family, failure_class, root_cause, fix, etc.). It distinguishes itself from siblings by focusing on the 'cryptic' infra error pattern matching library, whereas siblings like diagnose_trace or diagnose_batch likely handle 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?

Explicitly states when to use it: 'the moment you hit a transaction_simulation_failed, BlockhashNotFound, a -32xxx RPC code, a 4001/-32002 wallet error, an attestation failure, or any infra error you can't instantly resolve.' It also implies when not to use (for general trace/batch diagnosis via sibling names) and provides a clear gate contract for autonomous action, which is strong usage guidance beyond typical.

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?

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It goes beyond a simple read/write note by detailing latency behavior (instant for known patterns vs. up to 25s for novel failures), advising a timeout of 30s, and recommending async handling. It does not state side effects, but the diagnosis tool is presumably non-mutating; this is reasonable given the context. The latency disclosure is particularly useful.

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 two sentences, front-loaded with the core purpose, followed by operational latency guidance. There is minimal wasted text, and the structure is logical: what it does, then important usage caveat. It is concise without under-specifying.

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 one parameter and no output schema, the description is fairly complete: it lists the returned verdict fields, explains latency variability, and gives a timeout suggestion. It does not explain how to interpret the verdict fields in detail, but that is likely self-explanatory. The inclusion of the latency information fills a gap that schema/annotations lack. Overall, an agent has enough to decide when and how to invoke it.

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 single parameter 'trace' has a description ('OTel-shaped agent trace'). The tool description does not add further detail about the structure or format of the trace beyond what the schema already states. Per the rubric, with high schema coverage, a score of 3 is the baseline; the description adds no extra value for parameters.

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 what the tool does: 'Diagnose why an AI agent run failed' and lists the verdict fields returned. It is specific about the verb and resource, but it does not explicitly distinguish it from sibling tools like diagnose_batch or detect_loop, which are also diagnosis-related. The purpose is unambiguous enough for an agent to recognize its role.

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 to use the tool (when a run fails) but does not explicitly state when to avoid it or direct the agent to alternatives in the sibling set (e.g., detect_loop for loop detection or diagnose_infra_error for infrastructure issues). It provides latency guidance that could influence usage, but lacks explicit exclusions or comparisons.

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

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

With no annotations, the description carries the full burden. It discloses the return statuses, the fact that it is a read-only feedback loop, and that it costs no token. It could mention error behavior or what happens with an invalid request_id, but the core behavioral contract is clear.

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 main purpose and immediately provide the statuses and source of the parameter. Every sentence earns its place, including the cost note.

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 status-check tool with no output schema, the description covers purpose, input source, return values, and cost. It lacks details about failure cases or output structure, but the tool is simple enough that these are not critical gaps.

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%, so the description must compensate. It does so by explaining that request_id comes from request_pattern, giving the parameter meaningful provenance beyond the bare schema definition.

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 uses a specific verb ('Check') and a clear resource ('what happened to a pattern you requested'), and ties it to request_pattern's request_id. It also names the exact statuses returned, which makes the tool's job unambiguous and distinguishes it from siblings like request_pattern.

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 the input comes from request_pattern's request_id, so the intended workflow is clear: use this after requesting a pattern. It doesn't enumerate alternatives or exclusions, but for a simple status lookup the context is sufficient.

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

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

With no annotations, the description carries the burden of behavioral disclosure. 'Fetch' implies a read-only, non-destructive operation, and the added org-only constraint is a useful behavioral detail. It doesn't mention potential errors or return format, but for a simple fetch these are minor gaps.

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. Every piece of information (action, resource, identifier options, org scope) is essential and efficiently presented.

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 low-complexity tool with only two optional parameters and no output schema, the description covers the essentials: what it does, how to identify the target, and the scope restriction. It doesn't explain return structure, but that's often inferred for a fetch operation, so it's adequate.

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 has 0% description coverage, so the description must define the parameters. It states that the tool can fetch by id or by trace_id, which maps to verdict_id and trace_id, but it doesn't clarify whether one is required, if both are allowed, or precedence rules. This is partial compensation for the missing schema descriptions.

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 a specific verb (Fetch) and a specific resource (previously produced verdict), and distinguishes it by offering two identifier options (id or trace_id) plus an org-only scope. It avoids tautology and is instantly distinguishable from the sibling diagnostic 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?

The context of use is clear: when you have a verdict id or trace_id and want to retrieve a prior verdict. It doesn't explicitly name alternatives, but none of the siblings serve exactly this purpose, so the implied usage is sufficient. It lacks explicit when-not-to-use phrasing, lowering it from 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?

With no annotations, the description carries the behavioral burden. It discloses that this is a read-only personal summary and names the specific aggregates surfaced, but it does not mention data freshness, time range, output format, or whether results are live or cached. The description is helpful but not deeply transparent.

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-loads the essential value proposition and specific metrics. The middle sentence, 'Turns your input into visible collaboration,' is somewhat promotional and does not add operational information, but the overall structure is 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?

For a zero-parameter, no-output-schema tool, the description provides enough information for an agent to understand what the call returns and why it matters. The main missing context is explicit relationship to sibling tools and any caveats about scope or data timing.

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 has zero parameters, so the baseline per rubric is 4. The description adds relevant scoping context ('Token-scoped to you') that clarifies the implicit parameter space even though the schema is empty.

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 uses a specific verb ('See') and a specific resource ('your feedback + pattern requests ... shaped the shared library'), and enumerates the concrete metrics returned: verdicts rated, patterns requested, and patterns approved. This clearly distinguishes it from siblings like my_usage or what_others_did.

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 the tool is for viewing one's own contribution summary, but it never explicitly states when to choose it over alternatives such as my_usage (likely token/usage stats) or what_others_did (others' activity). No when-not-to-use or alternative-routing guidance is provided.

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

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

With no annotations, the description carries the full behavioral burden, and it discloses the tool's read-only nature, the specific metrics returned, the token scope, and that it is free. It does not detail response format or side effects, but for a zero-parameter usage query this is adequate.

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

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

The description is compact and front-loaded, immediately stating the core purpose, then listing specific returned values, and ending with actionable guidance and cost/scope notes. Every sentence contributes useful information without 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 no-parameter, no-output-schema introspection tool, the description is complete: it names all key returned metrics, explains the benefit (self-govern spend), gives usage guidance, and clarifies scope and cost. Nothing critical is missing for an agent 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?

The tool has zero parameters, so the baseline is 4; the schema already fully describes the parameter set as empty. The description adds relevant context about what data the tool reports, though it need not explain any parameters.

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 uses a specific verb ('See') and identifies a concrete resource: the caller's current usage and remaining allowance, with a detailed list of returned data (snapbacks, guard checks, estimated spend, % used, reset time). It does not explicitly contrast itself with sibling tools like budget_guard or my_impact, so it falls short of full sibling differentiation.

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

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

It gives clear usage context by saying 'Call it periodically to avoid surprises,' which tells the agent when to invoke it. It does not mention alternatives or when not to use it, so it lacks explicit exclusions.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It states the return format (ranked list of {failure_class, root_cause, fix_suggestion}) and implies a non-destructive read operation. It does not mention edge cases like empty results or ranking criteria, but the core behavior is transparent enough for an agent to call it safely.

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

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

Two sentences with zero waste. The critical 'BEFORE running' instruction is front-loaded, and the return structure is stated compactly. Every word contributes to the tool's purpose and usage.

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 read-only tool with three optional parameters and no output schema, the description provides the return structure, usage timing, and purpose. It does not explain how the optional parameters influence the ranking or what happens when no patterns match, but these are minor gaps. The description is sufficiently complete for an agent to decide when and how to invoke it.

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 each parameter (tags, limit, agent_stack) is documented. The description does not add extra meaning beyond the schema; it only refers to 'agent setup', which loosely maps to agent_stack but without further detail. Baseline 3 is appropriate when the schema already handles parameter documentation.

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

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

The description uses a specific verb ('get') and resource ('known failure patterns for a given agent setup'), and explicitly frames the tool as a pre-execution step with 'BEFORE running'. This clearly differentiates it from reactive diagnostic siblings like diagnose_trace and diagnose_batch, which focus on post-hoc analysis.

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 timing guidance: 'Call this before executing a plan and self-correct.' This is clear when-to-use advice. It does not explicitly mention alternatives or exclusions, but the 'BEFORE running' instruction and the sibling names (e.g., diagnose_*) make the intended context unambiguous. A small deduction for not naming an alternative directly.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It does this well by stating the tool is deterministic, costs no tokens, uses no LLM, and performs no network calls, reading only what the caller passes. It does not detail error behavior or output structure, but the core safety and privacy traits are explicit.

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

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

The description is front-loaded with the core question, then gives input requirements, an illustrative example, and behavioral guarantees. It is slightly verbose with the motivational Solana/Base example, but each sentence contributes either usage guidance or transparency information, so no sentence 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?

The tool has no output schema, so the description should clarify what the agent can expect back. It says 'deterministic routing advice with the reason,' which conveys the high-level return value but does not describe the structure, the possible action values, or how the reason is formatted. Inputs are well covered, but the output contract is under-specified.

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. The description adds meaning beyond the schema by explaining the relationship between parameters: pass the error plus 'current_chain, available_chains, and/or current_provider, available_providers'. The 'and/or' clarifies that chain topology and provider topology are independent optional inputs, which the schema alone does not convey.

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

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

The description names a specific decision task ('RETRY', 'SWITCH', 'FALL BACK', or 'STOP') and clearly states the tool produces deterministic routing advice with a reason. It also distinguishes itself from nearby diagnostic siblings by emphasizing it is free, LLM-free, and network-free, making its niche 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?

The description tells the agent when to use it: after an error, pass the error plus the configured topology, and receive routing advice. It gives a concrete motivating example ('flaky Solana RPC... switch to Base') but does not explicitly say when NOT to use it or name alternative tools for this situation.

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

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

With no annotations, the description carries the full disclosure burden and does well: it reveals that reporting feeds a shared crowd view, acts as safety telemetry, is token-scoped, and is free. It does not cover idempotency or repeated-report effects, but the main side effects and scope are clearly stated.

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

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

The description is dense but well-organized: purpose, parameter list, dual purpose, and scope/cost are each covered efficiently. The em-dash asides earn their place, though the text 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?

For a 6-parameter tool with no output schema and no annotations, the description covers the caller context, the parameters, the side effects, and the cost/scope. The main gap is the lack of semantics for three parameters裡class, family, confidence, which keeps it from being fully 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?

Schema coverage is 50%, and the description lists all six parameters but only clarifies 'succeeded' ('did the retry work?'). The undocumented parameters failure_class, family, and confidence are named but not given meaning, so the description only partially compensates for the schema gap.

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

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

The description states a specific verb and resource: report the outcome of an auto-applied fix alert. It goes further to explain the caller (self-heal interceptor) and distinguishes this from a generic outcome report by tying it to telemetry and the shared crowd view used by what_others_did.

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 clear context: use this after a gate-applied fix and its retry, and it explains why reporting matters. It does not explicitly spell out when not to use it or name alternatives, but the self-heal interceptor framing strongly implies the intended invocation path.

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

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

There are no annotations, so the description carries the full behavioral burden. It does disclose meaningful traits: 'It goes straight to our roadmap/backlog' and 'Free — no token needed,' which signal it is a low-cost, asynchronous request path. However, it does not mention what happens after submission, whether there is any confirmation, or relevant limitations, leaving some ambiguity for an agent deciding whether this is appropriate.

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 concise and front-loaded with the main action, followed by when-to-use scenarios and a closing behavioral note. Every sentence earns its place, and the 'Free — no token needed' detail is a useful, compact addition.

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 feedback/request tool with no output schema, the description covers the main operational context: how to use it, when to use it, and what happens to the request. The schema fills in parameter details, and the description's 'goes straight to our roadmap/backlog' clarifies the lack of immediate resolution. It could be slightly more explicit about expected outcomes or whether the user will receive a response, but it is 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 schema descriptions cover 100% of the parameters, so the baseline is 3. The description adds minimal parameter-level detail beyond the schema, such as emphasizing that messages should be specific ('be specific' appears in the schema, not the main description). It does not materially improve understanding of kind, context, or verdict_id beyond what the schema already provides.

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

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

The description clearly states the tool's purpose: 'ask us to add a failure pattern to the library, or report a problem we couldn't diagnose well.' It uses a specific verb and resource, making the core function evident. However, it does not explicitly differentiate itself from sibling tools like submit_feedback, though it does mention diagnose_trace as a related entry point.

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: 'Use this 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.' It provides clear context but does not state when not to use it or mention alternative feedback/request tools, so it falls short of full 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?

No annotations are provided, so the description carries the behavioral burden. It adds useful context with 'Free and needs no token,' covering auth and cost. However, it stops short of explicitly stating that the operation is read-only or non-destructive, and it doesn't describe output format or no-result 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?

Three tight sentences: the first states the function and scope, the second covers cost/auth, the third gives priority usage guidance. Every sentence earns its placeable and the core purpose is front-loaded.

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

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

For a two-parameter search tool with no output schema, the description covers purpose, usage timing, cost, and auth. It could mention return format or empty-result behavior, but the schema's 'limit' description already hints at section-based results, so the gaps are minor.

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

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

Schema description coverage is 100%, and both query and limit already have meaningful descriptions in the schema. The description's example ('how to format a trace') loosely maps to the query parameter but does not add any new parameter-level 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?

The description says 'Search Snapback's documentation' — a specific verb plus resource — and enumerates concrete content areas (trace formatting, tool behaviors, failure taxonomy, auth, pricing, errors). The purpose is unmistakable and visually distinct from the operational sibling tools like diagnose_trace or get_verdict, even though no sibling is 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?

'Call this first if you're unsure how to format a request or what a verdict means' is an explicit when-to-use trigger. It doesn't name alternatives or say when not to use it, but the guidance is clear enough for an agent to prioritize this tool in the appropriate situation.

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

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

With no annotations, the description carries the full burden. It discloses the side effect ('Frees the session') and the return content ('total steps, duration'), and even notes cost behavior ('Free, no token'). It does not mention irreversibility or ownership requirements, but the essentials are present.

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 sentences, with the primary action and key outcome front-loaded. Every word earns its place; no fluff or 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?

For a single-parameter, focused tool, the description covers purpose, behavior, side effect, and output summary. A slight gap is the lack of guidance about prerequisite state or where session_id comes from, but the tool is simple enough that this is not a serious omission.

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 only parameter, session_id, has 0% schema description coverage t: the schema just says it is a string. The description mentions 'session' but not how to obtain or format the ID. The parameter is self-explanatory, so no major issue, but the description adds no real semantic detail.

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 action ('Close'), the resource ('live session'), and the additional outcome ('get a short run summary'). It is distinct from siblings like session_start and session_step, making the tool's role unambiguous.

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 to use it: when a live session needs to be closed, presumably after session work is complete. It does not explicitly name alternatives or exclusions, but the intended context is clear enough for an agent.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses live/real-time behavior, return value, cost/auth implications ('Free, no token'), and the expected call pattern. It could mention side effects or session limits, but the key traits are transparent.

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 core purpose, then return value, then usage pattern. Every sentence earns its place; the style is efficient without being sparse.

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

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

The description states the return value (session_id) and the call sequence (session_step/session_end), which is essential since there is no output schema. It doesn't explicitly say the returned session_id must be passed to the siblings, but that is strongly implied. Minor gaps around error behavior or session lifecycle edge cases prevent a 5.

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 single optional agent_id parameter is already fully documented. The description adds no parameter-specific meaning, which is acceptable under the high-coverage baseline.

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 action ('Open a LIVE mid-run session') on a clear resource (Snapback session) with a distinct purpose: real-time warnings on loop/token/cost/context. Also differentiates from siblings by describing the session lifecycle with session_step and session_end.

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?

Clearly says when to use it: mid-run, for live guardian-mode monitoring. Also gives lifecycle usage ('Call session_step as you run, session_end when done'). It does not explicitly name alternatives or exclusions, but the context is strong enough for an agent to select it appropriately.

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

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

No annotations are present, so the description carries that burden. It discloses that warnings are advisory, that it returns them immediately, and that the tool is free. It does not explicitly state whether it modifies state, but 'Report' strongly implies a non-destructive telemetry 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 relatively long, but it front-loads the core purpose and returns warnings. It contains a minor typo (repeated 'context_window') and the counter list is a bit sprawling, but every sentence earns its place by clarifying functionality, inputs, or behavior.

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 nested objects and no output schema, the description explains that the return value is warnings (loop/budget), which is the key behavior. It does not detail the exact structure of the step object beyond the schema's 'action/tool + inputs', but that is already in the schema. It provides enough to call the tool correctly.

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

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

Schema coverage is 75% (3 of 4 params have descriptions). The description adds significant value by enumerating the expected fields inside the 'counters' object (step, max_steps, tokens_used, token_budget, etc.), which the schema only vaguely describes as 'running counters'. It does not mention loop_threshold, but the schema covers it.

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 ('Report') and resource ('ONE step of a live run') and clarifies the outcome (warnings). It distinguishes itself from siblings like detect_loop and budget_guard by focusing on step-by-step reporting during a live run.

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 clear context: this tool is for reporting a step during a live run and receiving advisory warnings to self-correct. It implies when to use it (mid-run) but does not explicitly point to alternatives or exclusions, though the context is strong enough.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, and it delivers: it reveals that the correction updates a SHARED pattern library, that patterns are anonymized, that trace content is never shared, and that correct/wrong verdicts are weighted accordingly. These are non-obvious side effects an agent must know before calling.

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

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

Four dense sentences, each earning its place: core purpose, when to call, side effects, and the sibling alternative. The most important information is front-loaded, and there is 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?

Coverage is strong for a simple feedback tool: purpose, timing, side effects, privacy, and routing are all present. The only omitted details are the response/acknowledgment format and error behavior, which are unlikely to affect 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?

The input schema already documents all three parameters with 100% coverage. The description reinforces the meaning of correct and note with context like 'did the fix work? what was wrong?', but it doesn't add materially new parameter semantics 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?

The description opens with a direct, specific verb and resource: tell Snapback whether a verdict was correct. It immediately distinguishes itself from request_pattern, so the agent can tell which tool to use 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?

Usage is fully specified: call it AFTER acting on a verdict and seeing the outcome, allow only ONE rating per verdict, and explicitly route new-pattern requests to request_pattern. This gives the agent unambiguous selection and timing 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?

With no annotations, the description carries the full behavioral burden. It adds valuable disclosure: 'Free, no token, no LLM' signals this is a lightweight, deterministic-looking helper, and 'scored by speed gained, accuracy lost, cost saved' explains what the ranking is based on. It does not detail output format or whether any action is taken, but the advisory nature is reasonably clear.

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 with the scenario, then lists the recovery options and adds a final no-cost guarantee. It is slightly stylized but every sentence contributes useful context.

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 7 optional parameters, no output schema, and no annotations, the description gives a clear scenario and expected result but leaves parameter semantics and return structure largely implicit. It is adequate for understanding the tool's purpose but not fully complete for precise invocation.

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

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

Schema description coverage is 0%, and the description only says to 'pass your counters' while mentioning token/context/cost budgets generically. It does not explain individual parameters such as recent_actions, nor does it clarify how budgets and usage relate or which inputs are needed for a meaningful result.

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 uses a specific verb and resource: it takes budget counters and returns ranked, least-disruptive recovery options. It clearly distinguishes itself from budget_guard by framing itself as the action-oriented follow-up to the alert, and it lists concrete recovery strategies.

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 opening question, 'Approaching a token/context/cost budget mid-run?', provides a clear when-to-use condition. It also positions itself relative to budget_guard, though it does not explicitly state when not to use it or name other alternative 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?

With no annotations, the description carries the full burden and does well: it discloses the return structure, privacy guarantees (no org/agent/trace identity), minimal aggregation threshold to prevent reverse-engineering, and the network effect. It doesn't discuss error cases or empty results, but the key behavioral traits are covered.

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 structured with a clear label ('THE CROWD:') and covers multiple aspects (purpose, return format, when to use, privacy, aggregation). While a bit verbose, each sentence adds value and it's front-loaded with the core 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 lookup tool with no output schema, the description explains the exact return format and key constraints (privacy, min-sample, aggregation). It gives examples of failure_class values in the schema and explains the error-mapping behavior, making it complete enough for an agent 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 coverage is 100% with detailed descriptions for both parameters, including the relationship between 'error' and 'failure_class'. The description mostly echoes this ('or pass the family/error and we'll map it') without adding new semantics, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool looks up what other agents did for a failure class and whether it worked, with a specific resource (crowd outcomes). It distinguishes from the 'single library answer' but doesn't name a sibling, so it's clear but not maximally differentiated.

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 'Use it when you hit a failure and want the crowd's verdict on what actually fixes it, not just the single library answer', giving a clear scenario. It doesn't mention when not to use it or name alternative tools, but the contrast with the library answer provides context.

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