trace-mcp

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

Beyond the readOnly/idempotent annotations, the description explains that the tool delegates to other tools, can invoke deferred tools without load_tools, enforces tools.exclude as a hard restriction, and documents the JSON return shape. This adds meaningful behavioral context not present in 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 cover purpose, use case, restrictions, read-only behavior, and return shape. Every sentence earns its place and key information is front-loaded.

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

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

Despite having no output schema, the description provides the return format. The schema covers parameter validation, annotations cover safety, and the description covers usage, restrictions, and batching intent. Nothing essential for an agent to call this correctly is missing.

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

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

The input schema already fully documents the 'calls' parameter with item schemas and min/max constraints, so the baseline is 3. The description adds value with concrete usage examples and clarifies that deferred tool names are acceptable, going slightly beyond schema-only information.

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?

Description states a specific verb ('Execute multiple trace-mcp tools in a single MCP request') and distinguishes itself from siblings by enabling batched dispatch, including deferred tools. It is immediately clear what this tool does and how it differs from individual tools like get_outline or search.

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 to reduce round-trips when you need several independent queries,' gives concrete examples, and clarifies when a tool is still not callable ('tools.exclude stays a hard restriction'). This gives clear when-to-use and when-not-to-use 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?

Even though annotations already declare readOnlyHint, idempotentHint, and destructiveHint, the description adds valuable behavioral context: the phantom god-node filter, how include_ambiguous_text_matched changes behavior, the read-only nature, and the return shape including truncation and total counts. No contradictions with annotations.

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

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

The description is front-loaded with purpose and routing, then packs behavioral nuances, read-only status, and return format into compact sentences. Every sentence earns its place; nothing is redundant or 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 no output schema, the description fully covers return values, truncation, ambiguous filtering, and page limits. It also addresses key behavioral edge cases and provides enough guidance for correct invocation despite having six optional parameters.

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 meaningful context beyond the schema: it explains the ambiguous text-matching flag's purpose, the pagination cap, and the structure of references. This helps the agent understand the interplay between parameters and results.

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 all references to a symbol or file (imports, calls, renders, dispatches)'. It further clarifies semantic vs. text matching and explicitly differentiates itself from siblings like search_text and get_call_graph.

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 'Use instead of Grep for symbol usages' and gives direct alternatives: 'For raw text use search_text; for a bidirectional call graph use get_call_graph.' This gives the agent clear routing guidance with little left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description reinforces 'Read-only'. More importantly, it adds non-obvious behavior: branches keep their direction, depth 2 means callers of callers and callees of callees, and the JSON response shape is provided. A small gap is unspecified behavior when neither fqn nor symbol_id is provided.

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

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

The description is compact and front-loaded: it opens with the core behavior, immediately explains depth semantics, provides an explicit alternative, and closes with output format. Every sentence earns its place with no redundancy or 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?

The tool is well covered: purpose, usage alternative, depth behavior, read-only safety, and return structure are all present, and annotations cover the safety profile. The main omission is that no parameter is required in the schema while the description assumes a symbol is centered, leaving the fqn-or-symbol_id contract implicit.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds useful semantics beyond the schema by explaining what depth means concretely ('callers of callers, callees of callees') and reinforcing the bidirectional traversal. It does not clarify how fqn and symbol_id relate or take precedence, but the main parameter semantics are 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?

The description is specific: it names the exact operation ('Build a bidirectional call graph centered on a symbol'), clarifies both call directions, and explains depth semantics. It also distinguishes itself from find_usages, making the tool's unique purpose immediately clear.

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 states when to use the tool ('Use to understand control flow through a function') and when not to, directing the agent to the correct alternative ('For flat list of all references use find_usages instead'). This is strong routing guidance among sibling tools.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior, and the description reinforces with 'Read-only' and adds the concrete JSON envelope. It also discloses that analysis is scoped only when symbol_ids is passed, which is useful context beyond 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?

Four compact sentences cover what the tool returns, how to scope it, when to use it, alternatives, read-only status, and return shape. 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?

Since there is no output schema, the description summarizes the return envelope and key report contents, plus usage context. It does not describe every parameter, but the 100% schema coverage covers those; the only minor gap is lack of any note about cost or performance for deep traversals.

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 each parameter. The description adds useful meaning for symbol_ids ('scope analysis to changed symbols only') but does not add meaning for fqn, depth, max_dependents, or decorator_filter beyond what the schema 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?

States 'Full change impact report' and enumerates distinct outputs (risk score, breaking change detection, enriched dependents, affected tests, hidden couplings), so an agent knows exactly what the tool returns and can distinguish it from sibling 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?

Explicitly says 'Use before modifying code to understand blast radius' and names alternatives: assess_change_risk for a quick risk score and get_call_graph for who-calls-what. This gives direct when/when-not routing.

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

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

Annotations already carry readOnlyHint=true and idempotentHint=true, and the description's 'Read-only' agrees with them rather than contradicting them. The description adds genuine behavior beyond annotations: token-budget packing, shared-import deduplication for batch queries, and the exact return shape (primary, imports, token_usage). It loses a point because the 'Returns JSON' claim ignores the markdown output_format option, and truncation/error behavior when the budget is exceeded is undisclosed.

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 tight sentences, each earning its place: function, batch/dedup semantics, routing to the sibling tool, and return shape. The core capability is front-loaded in the first clause with zero 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 6-parameter read-only tool with no output schema, the description covers the essentials: return shape, token budget behavior, batch semantics, and the lighter alternative. Gaps remain at the edges — the interplay between fqn/symbol_id/symbol_ids and behavior when the token budget is exceeded — but the per-parameter schema descriptions and rich annotations carry much of that load.

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 schema already documents all six parameters. The description earns an extra point by adding intent behind key parameters: 'packed within a token budget' clarifies the purpose of token_budget, and 'batch queries with shared-import deduplication' gives symbol_ids behavioral meaning beyond its bare listing.

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-object pair — 'Get a symbol's source code + its import dependencies + optional callers' — making the tool's function unmistakable. It also explicitly differentiates itself from get_symbol, its closest sibling, by describing what this tool bundles that get_symbol does not.

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?

Provides explicit routing rules: 'Use instead of chaining get_symbol calls' for import-heavy or batch needs, and 'For a single symbol without imports, use get_symbol — lighter' as the exclusion condition with the alternative named. This is exactly the when/when-not guidance this dimension requires.

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 behavior; the description adds value by specifying the data source (manifests), the read-only nature, and the exact return shape { detected, covered, gaps }. This goes beyond the structured annotations without contradicting them.

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 core purpose, followed by the read-only trait and return shape. Every sentence earns its place, with no redundant elaboration.

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, read-only report with no output schema, the description is complete: it explains what data is gathered, from where, and what the JSON response contains. An agent has enough information to invoke and interpret the tool correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description provides enough context about the returned fields to make the no-argument call understandable, and there is no parameter documentation 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 clearly identifies the tool as producing a technology profile with detected frameworks/ORMs/UI libs and coverage gaps, which is specific and not a tautology. It distinguishes the report's focus on plugin coverage from siblings like get_optimization_report or get_usage_trends, though it does not explicitly name any sibling.

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

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

Usage context is implied rather than stated: an agent can infer this tool is for inspecting project technology coverage and gaps, but there is no explicit 'use when' guidance or mention of alternatives. No exclusion criteria are 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?

Annotations already cover read-only, idempotent, and non-destructive behavior. The description goes beyond annotations by revealing that the tool invokes external type-checker processes and that its output is a mapping from errors to enclosing AST symbols. It does not mention prerequisites like checker availability or possible slowness, but the core behavioral profile is 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?

One tight sentence with the action verb front-loaded. Every phrase earns its place: the checker set, the mapping behavior, and the read-only property. 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?

Without an output schema, the description carries the burden of explaining results; 'map errors to enclosing AST symbols' conveys the core return shape. Combined with 100% schema coverage and strong annotations, this is mostly complete, though a hint about failure modes when invoking external checkers would round it out.

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 documents all 5 parameters. The description's mention of the three checkers mirrors the enum and adds no deeper meaning; the filtering and limit parameters are already well-described in the schema. This is the baseline case where the schema does the heavy lifting.

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 ('Execute') with a concrete resource ('type-checker (tsc, mypy, pyright)') and a distinctive outcome ('map errors to enclosing AST symbols'). This clearly differentiates it from siblings like get_index_health or get_coverage_report, which target different concerns.

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?

No guidance is given about when to choose this tool over the many related get_* siblings (get_index_health, get_coverage_report, get_optimization_report, etc.). The 'Read-only' tag states a property, not a selection criterion; there is no exclusions or alternatives mentioned.

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

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

Despite strong annotations (readOnly, idempotent, non-destructive), the description adds meaningful behavioral detail: token budget behavior, output format variants, timeout cap with default value, and a degraded response shape on timeout. It also confirms the read-only nature, aligning with annotations. 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?

The description is dense and front-loaded, with the core purpose and usage guidance first. It packs output shapes, timeout behavior, and alternatives into a compact block. Minor redundancy exists ('Read-only' repeats the annotation) and the toon reference is slightly tacked on, but overall every sentence 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?

With no output schema, the description properly explains return formats and the degraded timeout case. It covers tool selection, read-only semantics, token budget, and output options. Given the tool's moderate complexity and annotations already handling safety, 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?

Schema coverage is 100% and the schema already documents all four parameters, including defaults, enums, and constraints. The description reinforces token budget and output format behavior but does not add substantive per-parameter meaning beyond the schema, so the baseline 3 is appropriate.

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

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

The description states a specific action ('Search code by keyword/topic'), a precise result ('ranked source snippets'), and an explicit constraint ('within a token budget'). It also distinguishes the tool from siblings by naming get_task_context and search as alternatives, so an agent can tell them apart immediately.

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

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

It gives an explicit when-to-use condition ('when you need to READ actual code for a concept or feature') and clear routing instructions: use get_task_context for structured task context with tests and entry points, and search for symbol metadata without source. This is exactly the kind of differentiation agents need.

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?

The description states 'Read-only, no side effects' and describes the exact JSON return shape. While annotations already signal read-only/idempotent behavior, the description adds useful context about the response fields and pipeline progress, going beyond what annotations provide.

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

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

The description is compact and well-structured: purpose in the first sentence, usage guidance in the second, and return format in the third. Every sentence contributes meaningful 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?

Given the tool has no parameters and no output schema, the description is complete: it states purpose, safety, usage timing, and return fields. An agent can invoke this tool confidently without needing additional context.

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

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

The tool has zero parameters, so there is no parameter documentation burden. The description appropriately focuses on return value semantics instead, which is the relevant information for invoking the tool correctly.

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 identifies the tool's purpose with a specific verb and resource: 'Get index status, statistics, health, and pipeline progress.' This distinguishes it from sibling tools like get_session_stats or get_coverage_report by focusing on the index health and pipeline state.

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 states when to use it: 'Use to verify the index is ready before running queries.' It lacks explicit exclusions or named alternatives, but the usage context is clear and actionable.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety type is covered. The description adds value beyond annotations by describing the JSON return format ({ patterns: [{ type, description, savings_estimate }], total_waste }) and stating it 'Provides savings estimates.' No contradiction with annotations.

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

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

Three sentences, each earning its place: the first names specific waste patterns, the second covers read-only safety and savings estimates, the third gives the return shape and sibling routing. 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?

For a simple one-optional-parameter tool with no output schema, the description provides the return JSON structure, the tool's scope, and explicit sibling alternatives. 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 input schema covers 100% of the single parameter, including enum values and default. The description does not add any parameter-level detail, so the schema carries the full burden. 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?

The description opens with a specific verb and resource: 'Detect token waste patterns in AI agent sessions,' then lists concrete pattern types (repeated file reads, Bash grep instead of search, large file reads, unused trace-mcp tools). It also provides the return shape and distinguishes itself from siblings by naming their use cases.

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 to alternatives with conditions: 'For usage/cost overview use get_session_analytics; for A/B savings comparison use get_real_savings.' This tells the agent when not to use this tool and which sibling to pick instead.

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 readOnlyHint and idempotentHint annotations, the description adds meaningful behavioral detail: it is signatures-only, cheaper than Read, expands nested declarations with parentId+depth up to max 3, and specifies the exact JSON return shape. No contradiction with annotations.

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

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

The description is compact and front-loaded: purpose, use case, follow-up, nested behavior, read-only flag, return shape, and format note appear in a logical order. Every sentence earns its place; there is no filler or repetition of schema details.

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

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

Despite having no output schema, the description provides the full JSON return shape and all key behavioral constraints. Parameter semantics are covered by high schema coverage, and usage vs. alternatives is explicit. For a read-only listing tool this is complete enough to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the nested=true effect (expands large top-level symbols, default ≥100 LOC, max depth 3) and noting output_format 'toon' support, which goes slightly beyond the schema's per-parameter text.

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

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

The description states a specific verb+resource ('Get all symbols for a file') and immediately clarifies scope ('signatures only, no bodies'). It also distinguishes itself from the sibling get_symbol and from Read by noting it is cheaper for understanding a file before editing, which is strong 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?

The description explicitly says when to use this tool ('before editing' to understand a file, 'cheaper than Read') and names the follow-up alternative ('get_symbol') for reading a symbol's source. It also explains when nested expansion applies, giving clear practical usage direction.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description reinforces this with 'Read-only' and adds the return JSON shape (active_preset, registered_tools, etc.), disclosing what the agent will receive. This extra context goes beyond 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?

Two concise sentences, front-loaded with the core purpose and followed by a compact JSON key listing. Every sentence adds value; 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?

For a zero-parameter read-only introspection tool, the description is complete: it states what the tool reports, the read-only nature, and the exact response fields. There is no output schema, so the description carries the burden of return-value disclosure and does so adequately.

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 schema coverage is trivially 100%. Baseline for zero-parameter tools is 4; the description need not document parameter semantics because there are none.

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 ('Show') and enumerates the exact resources: active tool preset, available presets, registered tools, and deferred tools. It clearly differentiates this introspection tool from the many sibling get_* tools and explicitly connects deferred tools to load_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 description makes the tool's context clear: use it to inspect tool registration and preset state. It mentions that deferred tools are loadable via load_tools, providing adjacent guidance, though it does not explicitly state when not to use it or name a directly competing 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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context beyond that: it confirms 'no side effects', suggests a cheap orientation call pattern, and specifies the return shape. This exceeds the annotation baseline without contradicting it.

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 concise sentences front-load the core behavior and return shape. The 'Read-only, no side effects' clause is slightly redundant with annotations, but the rest earns its place by adding usage guidance and output fields.

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 complete for a simple, optional-parameter read-only tool. It names the return JSON fields, gives a recommended invocation, and explains the tool's role. It could mention symbolCount semantics or potential costs, but nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents the only parameter. The description adds the session-start use case for summary_only=true, which is helpful, but it does not add meaning beyond what the parameter description already conveys.

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

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

States a specific verb ('Get') and resource ('project map') and enumerates contents (frameworks, languages, file counts, structure). It does not explicitly distinguish itself from sibling tools like get_outline or get_context_bundle, but the term 'project map' combined with the described fields is clear enough for an agent to understand what it returns.

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?

Provides clear usage context: call at session start with summary_only=true to orient before diving into code, and use instead of manual ls/find. It does not discuss when not to use it or name alternative tools, but the intended scenario is explicit and actionable.

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, and non-destructive hints, so the description does not need to repeat safety traits. It adds useful behavioral context by describing the exact return shape: files with raw_tokens, compact_tokens, savings, and total_savings. This is valuable because there is no output 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 description is compact and front-loaded with the core purpose, then clearly differentiates the tool from a sibling, and finishes with the return JSON shape. 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 simple read-only tool with one optional parameter, the description is complete: it explains what the tool does, when to use it, what it returns, and how it differs from the closest sibling. No important context is missing.

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

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

Schema coverage is 100%, and the only parameter, period, is fully documented in the schema with an enum and default of 'week'. The description does not add parameter-level meaning beyond the schema, which is expected given high coverage.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'A/B comparison: how many tokens could be saved by using trace-mcp instead of raw Read/Bash file reads.' It also specifies the per-file breakdown, making it easy to distinguish from other reporting tools like get_optimization_report.

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 directs when to use this tool versus an alternative: 'For pattern-based waste detection use get_optimization_report instead.' This provides a clear exclusion and alternative, so an agent can route correctly without opening the schema.

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

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

Annotations already mark it read-only and idempotent; the description adds beyond that by noting it 'Parses Claude Code JSONL logs automatically' and specifies the exact return shape. It does not over-disclose or contradict 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?

Four short, information-dense sentences. The main action is first, then a behavioral note, then alternative routing, then the return format. 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?

For a read-only analytics tool with no output schema, the description compensates by stating the return JSON structure and parsing behavior. It lacks explicit prerequisites like 'log files must exist,' but the parameters and routing are sufficiently covered.

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

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

Schema coverage is 100%, with both 'period' and 'session_id' described in the schema. The description does not add parameter-specific semantics, but the schema fully covers it, so a baseline 3 is appropriate.

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

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

The description uses a specific verb ('Analyze') with a clear resource ('AI agent session logs') and enumerates the concrete outputs (token usage, cost breakdown, top files, models). It also distinguishes itself from sibling tools by naming what it is not for.

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 alternatives: 'For waste detection use get_optimization_report; for cost trends use get_usage_trends.' This gives clear routing guidance and prevents mis-selection.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, so the description is not burdened with those disclosures. It adds valuable behavioral detail by specifying the returned JSON structure—session with latency_per_tool, cumulative, dedup_saved_tokens, and report—which is especially useful given there is no output 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 description is a single, front-loaded sentence that leads with the purpose and follows with a compact return layout. It contains no filler, though the inline JSON example is somewhat dense and could be slightly clearer as a structured list.

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, read-only metrics tool, the description covers purpose, scope, and output shape adequately. It does not clarify how 'session' is defined or when a sibling analytics tool would be more appropriate, leaving a small but meaningful gap for an agent selecting among similar tools.

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?

There are zero parameters and the schema coverage is trivially complete, so the baseline is 4. The description reinforces that the tool is parameterless by scoping everything to 'this session,' but it does not need to add more parameter-level meaning.

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 identifies the resource ('this session') and the concrete purpose ('Token savings stats'), and enumerates the metrics returned: per-tool call counts, token savings, reduction percentage, dedup savings, and latency percentiles/error rate. It is clear and specific, but it does not explicitly distinguish itself from overlapping siblings like get_session_analytics.

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 'for this session' implies that the tool should be used when an agent wants token-savings metrics for the current session, which provides some usage context. However, the description gives no explicit guidance about when not to use it or how it compares to alternatives such as get_session_analytics, get_optimization_report, or get_real_savings.

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, and non-destructive behavior. The description adds useful context beyond annotations: it returns only the symbol rather than the whole file and provides the response shape. It does not mention the verify_against_git comparison behavior or git_mismatch in the return payload, though that is documented in the parameter schema, so this is a minor omission rather than a 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?

The description is compact and front-loaded with the core purpose. It packs usage guidance, behavioral scope, read-only information, and return shape into three sentences with no wasted words.

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 provides a return shape despite the lack of an output schema and clearly routes between siblings. However, it does not explicitly state that exactly one of symbol_id or fqn is required, and the verify_against_git behavior only lives in the schema. These are real but minor gaps given the otherwise rich annotation and schema context.

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

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

Schema description coverage is 100%, so the schema already explains each parameter. The description reinforces that either symbol_id or fqn can be used, but it does not add significant meaning beyond the schema for max_lines or verify_against_git. This matches the baseline for fully covered schema 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 opens with a specific verb and resource: 'Look up a symbol by symbol_id or FQN and return its source code.' It clearly distinguishes the tool from Read and get_context_bundle, so an agent can immediately understand what it does and which sibling it is not.

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

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

The description gives explicit usage direction: 'Use instead of Read when you need one specific function/class/method' and 'For multiple symbols at once, prefer get_context_bundle.' This tells the agent when to select this tool and when to select a sibling.

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, and the description reinforces these with 'Read-only.' It adds value by disclosing the output formats (JSON default or Markdown) and the adaptive-by-task-type behavior. No contradiction with annotations is present, and the extra output-format detail goes beyond what annotations provide.

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

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

The description is compact and front-loaded: the first sentence states the core purpose, the second gives direct usage guidance, and the third handles sibling differentiation. Every sentence earns its place with no redundant 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?

Given six parameters, a rich schema, and no output schema, the description covers the essential call-or-not decision and high-level output shape. It names the context contents (execution paths, tests, entry points) and output formats, though it does not enumerate the exact JSON fields returned; this is a minor gap for an all-in-one context tool but not blocking.

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 explains all six parameters, including task, focus, detail_level, token_budget, include_tests, and output_format. The description does not need to compensate for parameter gaps and adds only general context about output format, which is already reflected in the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as the all-in-one context for starting a dev task, listing concrete contents (execution paths, tests, entry points) and how it adapts by task type. It also explicitly distinguishes itself from the sibling get_feature_context, so an agent can tell them apart without inspecting 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 gives explicit when-to-use guidance: 'Use as your FIRST call when beginning any new task' and frames it as a replacement for manually chaining search → get_symbol → Read. It also directs narrower feature-code lookups to get_feature_context, providing a clear alternative and exclusion condition.

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 read-only nature disclosed in the description is consistent but not new. The description adds value by revealing the exact return shape (JSON with days, daily array, totals) and the daily time-series granularity, which the annotations do not 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?

Three dense sentences with no fluff. The main purpose is front-loaded, the use case and alternative follow immediately, and the return format is compactly summarized. Every sentence 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?

The tool has only one optional parameter, no output schema, and low complexity. The description covers the purpose, the use case, the alternative tool, the safety profile is in annotations, and the return JSON shape is fully specified. There is nothing an agent needs to call this correctly that is missing.

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

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

Schema coverage is 100% with the parameter description already stating it is the number of days and the default of 30. The tool description adds no additional semantics for the 'days' parameter, but it does corroborate that the output contains a 'days' field, which is minimal extra context. 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 and resource: produces a daily token usage time-series with sessions, tokens, estimated cost, and tool calls. The phrase 'For spotting cost spikes' clarifies the intended use, and it explicitly differentiates itself from get_session_analytics, so an agent can distinguish it from siblings 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?

Gives an explicit use case ('For spotting cost spikes') and names the alternative when a different need exists ('For detailed session breakdown use get_session_analytics instead'). This gives clear selection criteria with no inference required.

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?

The description discloses key behavioral traits beyond annotations: the decision remains for historical queries, is excluded from active queries, mutates the decision store, and is idempotent. It also specifies the return shape. This adds meaningful context beyond 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?

Four short sentences, each carrying useful information: the action, the historical/active distinction, the usage condition, and the return format. No filler or redundancy; the most important 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?

Given the absence of an output schema, the returned JSON is explicitly stated. The mutation, idempotency, and retention behavior are all covered. The tool's effect on the knowledge graph and query behavior is clear, making it complete for the agent to invoke correctly.

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

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

Schema description coverage is 100%, so both id and valid_until are documented there. The description itself does not add much parameter-level meaning beyond the schema, but it correctly implies valid_until is part of the return object. 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 uses a specific verb ('Mark as no longer valid'), names the resource ('decision'), and clearly defines the outcome: the decision stays in the knowledge graph for historical queries but is excluded from active queries. This differentiates it from siblings like remember_decision and query_decisions.

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 the tool: 'Use when a decision is superseded or reversed.' It does not name alternative tools or give when-not-to-use guidance, but the usage context is clear enough for an agent to select it correctly.

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?

The description discloses behavior beyond the annotations: it emits notifications/tools/list_changed, returns loaded tools' schemas, and remains usable even if the client ignores the notification (via batch). It also lists the exact JSON response fields, giving the agent a clear model of side effects and results.

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 efficient: it front-loads the core purpose, then covers invocation modes, side effects, and return shape in a few sentences. No sentence is filler, and the structure makes the most important information immediately visible.

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

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

Despite having no output schema, the description names all return fields and explains the notification behavior and batch fallback. Combined with the annotations signaling read-only/idempotent behavior, the description gives the agent enough context to invoke the tool correctly and interpret its response.

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 describes both parameters with 100% coverage, including the union behavior between `tools` and `preset`. The description adds value by specifying the no-arguments listing behavior, which is a parameter-level semantic not captured by the schema alone.

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 ('load') with a clear resource: deferred tools for the session's preset, by preset name and/or explicit names. It also distinguishes the no-argument listing mode, making the tool's purpose unambiguous and distinct from siblings like get_preset_info.

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 usage context: call with no arguments to list deferred tools, or pass preset/tool names to load them. It does not explicitly mention alternatives or when-not-to-use conditions, but the provided context is sufficient for typical invocation.

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?

The description explicitly states "Mutates the decision store; idempotent," and "Skips already-mined sessions unless force=true." This adds meaningful behavioral context beyond the annotations, specifying exactly what side effect occurs, the idempotency guarantee, and the skip behavior. It aligns with idempotentHint=true and readOnlyHint=false, with no contradictions.

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 dense: two sentences carrying purpose, strategy tradeoffs, behavioral notes, and return shape. It front-loads the core purpose, uses structured lists for strategies, and contains no filler. 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 tool with 7 optional parameters, no output schema, and moderate complexity, the description supplies the return JSON structure, strategy cost/recall tradeoffs, mutation behavior, and skip logic. Combined with 100% schema coverage, an agent has everything needed to select and invoke the tool correctly.

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

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

Schema coverage is 100%, and the schema already documents all 7 parameters with detailed descriptions, including enum choices, thresholds, and the incremental_cursor override. The description merely summarizes strategy and force, adding no new semantic information beyond what the schema already 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?

The description opens with a specific verb and resource: "Mine Claude Code / Claw Code session logs for architectural decisions, tech choices, bug root causes, and preferences." This clearly distinguishes it from sibling read/query tools like search and query_decisions by stating it processes session logs and mutates the decision store. The purpose is 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 gives concrete guidance on strategy selection (regex vs llm vs hybrid) and explains the skip-already-mined behavior with force=true. However, it never explicitly names alternatives or states when NOT to use this tool (e.g., "use query_decisions instead to read stored decisions"). Context is clear but exclusions are absent.

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

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

Annotations already mark this read-only, idempotent, and non-destructive, and the description reinforces this with 'Read-only.' It adds behavioral context by explaining the tool's combined search/journal/risk mechanism and its role in preventing empty-result hallucinations, going beyond what annotations alone 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?

The description is information-dense and mostly front-loaded, starting with the primary purpose and usage call-to-action. The long enumeration of combined capabilities and the slight redundancy between 'Returns...' and 'Returns JSON: {...}' keep it from being perfectly concise, but every sentence contributes needed 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?

Despite the absence of an output schema, the description states the JSON shape, the verdict values, the provenance of ranked targets, scaffold hints, and recommended next steps. Combined with the explicit usage instruction and alternative tool pointer, an agent has what it needs to invoke the tool correctly on a new task.

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

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

Schema description coverage is 100%, and each parameter already has a clear description with defaults and constraints. The tool description does not meaningfully add parameter-level guidance, so it meets the baseline but does not exceed 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 opens with 'Opening-move router for new tasks' and lists a concrete deliverable set: verdict, confidence, ranked targets with provenance, scaffold hints, and recommended next tool calls. It also explicitly distinguishes itself from get_task_context, so an agent can select it correctly among siblings.

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 states exactly when to use it: 'Call this FIRST on a new task to break the empty-result hallucination chain.' It also names the alternative, get_task_context, and the condition for preferring that instead ('broader task context with source code'), giving clear, actionable 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?

Goes well beyond the readOnly/idempotent/destructive annotations by disclosing the default review-tier filter, cluster_ids on clustered rows, the JSON response shape, and the timeout cap with degraded response `{ decisions: [], total_results: 0, degraded: true }`. It also mentions staleness verification and output_format support, giving the agent a realistic picture of 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?

The description is front-loaded with purpose and filters, then moves through scoping, defaults, return shape, format, and timeout. Every sentence earns its place, and the order is logical—no filler or 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?

With no output schema, the description provides the full return contract (`decisions`, `clusters_summary?`, `total_results`) and a timeout edge case. For a complex 17-parameter tool, it covers defaults, scoping, response behavior, and failure mode, leaving only the fine-grained parameter mechanics to the already-detailed 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% with detailed descriptions for all 17 parameters, so the baseline of 3 applies. The main description repeats a couple of hints (service_name scoping, review tier defaults) but adds no meaning beyond what the schema already provides for individual 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?

States a specific verb and resource ('Query the decision knowledge graph') and anchors it to the concrete question 'why was this architecture chosen?' with the actual decision record. This clearly distinguishes it from sibling mutation tools like remember_decision and invalidate_decision, and from a single-record getter like get_decision.

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 invocation context: 'Use service_name to scope to a subproject' and 'Defaults to auto+human-approved decisions; use include_pending or review_status for other tiers.' However, the main description does not explicitly name an alternative tool or state when not to use this tool; the only alternative hint (get_decision) appears in the index_only parameter description rather than the main description.

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

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

Annotations already carry idempotentHint=true, readOnlyHint=false, and destructiveHint=false; the description confirms these ('Mutates the index; idempotent') without contradicting them. It adds real value beyond annotations: search-cache invalidation, duplicate-symbol flagging, the once-per-file reporting constraint, and the exact JSON return shape. Minor gap: no mention of error behavior when the file path is invalid.

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 purpose, then usage guidance, then the duplication caveat, then the return format. Each sentence earns its place and the information is ordered by importance. Slightly dense, but not padded — no redundancy with the schema or annotations.

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

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

Complete for a single-parameter mutation tool: it covers what happens (reindex, cache invalidation), when to use it (after Edit/Write, lighter than full reindex), its idempotency, a caveat (duplication warnings, reported once per file), and the return structure in the absence of an output schema. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% — the single parameter file_path is fully documented as 'Relative path to the edited file.' The description references the file only implicitly through the return JSON ({ file }), adding no semantic detail beyond the schema. Baseline 3 is appropriate since the schema carries the parameter meaning.

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 ('Notify trace-mcp that a file was edited'), and precisely scopes what happens: reindex the single file and invalidate search caches. It clearly differentiates from the read-oriented siblings (get_index_health, get_symbol, search) by being a mutation, and positions itself as the lightweight single-file counterpart to a full reindex.

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

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

Gives explicit when-to-use guidance: 'Call after Edit/Write to keep index fresh — much lighter than full reindex.' It names the alternative (full reindex) and the deciding condition. It also routes a follow-up question to a sibling ('check_duplication re-asks'), so an agent knows which tool to pick next.

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?

The description contradicts the annotations: it says 'Live agent write into the decision knowledge graph' and discusses persistence, while annotations declare readOnlyHint=true. Per the scoring rule, this contradiction forces a score of 1. The otherwise rich behavioral detail (confidence routing, dedup, rate limit) cannot be trusted alongside contradictory metadata.

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 core action, and every sentence contributes useful information: routing behavior, usage context, alternatives, and return shape. The middle sentence is dense but still readable.

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 9-parameter tool with no output schema, the description covers the important non-schema context: confidence tiers, review queue behavior, dedup/rate-limit, and the JSON return shape. It could add permission requirements or rate-limit specifics, but the essentials are present.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters. The description adds almost nothing parameter-specific beyond connecting session_id to dedup/rate-limit behavior, 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 names a specific action ('write into the decision knowledge graph') and clearly differentiates from siblings by referencing add_decision and mine_sessions. The confidence-routing behavior further clarifies what this tool uniquely does.

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

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

Explicitly states when to use it ('during a session to capture decisions in real time') and names two alternatives with their appropriate conditions: add_decision for manual high-confidence writes and mine_sessions for post-hoc extraction. This gives an agent 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?

Annotations already declare readOnlyHint and idempotentHint, and the description's 'Read-only' adds no new safety information. However, it does add non-obvious behavior: the JSON result shape, mode-specific shape variation, and support for the compact 'toon' output format.

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: purpose first, then routing guidance, then output behavior. Every sentence carries useful information 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?

It provides the essential return shape and mode caveat, plus sibling routing, which is good for a tool with 20 params and no output schema. The non-single mode-specific shapes are not enumerated, leaving some ambiguity for agents invoking those 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning around the mode parameter by warning that non-single modes change the return shape. It also highlights output_format support, which supplements the schema enum.

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 'Search symbols by name, kind, or text', naming a specific verb, resource, and scope. It also explicitly distinguishes itself from search_text and find_usages, so an agent can tell it apart from the closest siblings without inspecting schemas.

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

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

It explicitly says to use this tool instead of Grep for code symbols and directs raw text/comment search to search_text and references to a known symbol to find_usages. This gives clear when-to-use and when-not-to-use 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 already declare readOnlyHint=true and destructiveHint=false, and the description independently states 'Read-only.' Beyond annotations, it discloses the return JSON shape, grouping behavior, and the cost nuance that 'a long path is paid once.' It doesn't discuss rate limits or indexing freshness, but the description adds meaningful behavioral context beyond the schema and annotations.

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

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

The description is compact and front-loaded with the core purpose, then adds routing guidance, safety info, return shape, and grouping nuance. It is a bit dense with multiple clauses in one sentence, but every sentence earns its place and the structure is logical. Slightly long but not wasteful.

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

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

For a read-only search tool with 9 well-documented parameters and an explicit return JSON shape, the description covers the key decision factors: what it searches, how to filter, how grouping changes the response, and when to use the sibling. It doesn't cover timeout defaults or max_results limits, but those are in the schema. Given no output schema, the return shape description compensates well.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters. The description adds some meaning by naming regex/glob/language filter support and explaining the grouping difference between 'by_file' and 'flat', but the schema already carries most of the semantic weight. Baseline 3 is appropriate because the description adds only modest value 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 precisely states what the tool does: full-text search across indexed files, with explicit support for regex, glob file patterns, and language filtering. It clearly differentiates from the sibling 'search' tool by stating that search_text is for strings/comments/TODOs/config values/error messages, while symbol search (functions, classes) should use 'search' instead.

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 versus the alternative: 'For symbol search (functions, classes) use search instead.' This direct routing to a sibling tool gives the agent clear selection criteria. It also names the read-only nature and describes the return shape, giving the agent enough context to decide whether this tool fits the task.

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?

The description confirms read-only behavior, consistent with the readOnlyHint/idempotentHint annotations, and adds a concrete response shape even without an output schema. It does not mention edge cases like rate limits or authentication, but these are less critical for a read-only onboarding helper.

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?

Every sentence earns its place: the onboarder identity is front-loaded, usage timing is clear, the alternative is named, and the JSON return shape is compactly listed. There is no filler or redundant schema 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 zero-parameter read-only tool with no output schema, the description covers purpose, output fields, usage timing, and the relevant sibling. Nothing an agent needs to call this correctly is missing.

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

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

The tool has zero parameters, so schema coverage is trivially 100% and the baseline is 4. The description adds no parameter details because there are none; instead it clarifies what the no-input call returns, which is sufficient.

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 ('shows') and names the resource types it exposes: top imported files, connected symbols, language stats, and example tool calls. It also explicitly differentiates from get_project_map, so an agent can distinguish it from siblings without opening schemas.

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

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

It states the exact condition for use — 'Call this first when exploring an unfamiliar project' — and names the alternative, get_project_map, for a structured project map. This gives clear when-to-use and when-not-to-use guidance with an explicit replacement.

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