Server Quality Checklist

Tool Scores

• get_whyA
  4.3/5.0
  Behavior5/5

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

  With no annotations, the description carries the full behavioral disclosure burden. It reveals key behaviors: fallback to git archaeology when no decisions exist, never-empty results, provenance/evidence_refs semantics, shared evidence meaning, and the answer_basis lane distinction. This is substantially more transparent than typical tool descriptions.

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

  Conciseness4/5

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

  The description is dense but every sentence earns its place, covering purpose, usage timing, query modes, behavioral semantics, and arguments. The backtick-wrapped terms add mild noise, but the structure is logical and front-loaded with the core purpose.

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

  Completeness5/5

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

  For a tool with five parameters, no annotations, and complex multimodal behavior, the description is remarkably complete. It explains all query modes, fallback behavior, result semantics, and parameter roles. The output schema exists, so not detailing the exact response format is acceptable; the agent has enough information to invoke and interpret results.

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

  Parameters4/5

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

  Schema description coverage is 0%, so the description must compensate. It documents all five parameters (query, targets, repo, id, reference) with functional meaning and even notes caller conveniences like accepting id and repository together. Some entries are terse (e.g., "repo: usually omitted"), but overall the parameter semantics are well covered.

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

  Purpose4/5

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

  The description clearly states the tool explains code decisions and evidence ("Why this code is shaped this way — decision records + evidence commits") and enumerates concrete query modes. It does not explicitly differentiate from siblings like get_answer or get_context, but its purpose is specific and not confusable after reading.

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

  Usage Guidelines4/5

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

  The description gives an explicit trigger condition ("Call before refactors or pattern divergences") and describes all invocation modes. It does not name alternative sibling tools or state when not to use it, but the usage context is clear enough for an agent to decide.

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

• get_dead_codeA
  4.5/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden and does an excellent job: it discloses how invalid 'kind' values are handled, that 'limit' is clamped, that min_confidence accepts numeric values or tier names, that safe_only means deletion-ready findings, and that workspace mode lowers confidence. These are meaningful behavioral traits that an agent would not otherwise know.

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

  Conciseness4/5

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

  The description is long but appropriately so for 14 undocumented parameters, and it front-loads the core use case before the parameter list. Each argument line is terse and informative; there is minor redundancy in repeating tier thresholds across min_confidence and tier, but it's justified because both parameters accept tier concepts.

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

  Completeness5/5

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

  Given 14 parameters, no annotations, and no schema-level descriptions, the definition is strikingly complete: it covers every parameter, explains non-obvious behaviors, provides usage context, and mentions rollups and confidence-lowering behavior in workspace mode. Since an output schema exists, the lack of detailed return-value documentation is not a gap.

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

  Parameters5/5

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

  Schema description coverage is 0%, so the description must fully compensate, and it does: every one of the 14 parameters gets its own explanation with defaults, allowed values, and edge-case behavior. For example, min_confidence is documented with both numeric thresholds and tier-name equivalents, and kind documents what happens with unrecognized input.

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

  Purpose4/5

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

  The description clearly identifies the resource: dead code (unused exports, unreachable files, zombie packages) and communicates the core capability of tiering findings by confidence. It does not use a single explicit verb like 'return' or 'list', and it doesn't explicitly distinguish itself from sibling tools, but the dead-code focus makes the purpose unambiguous.

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

  Usage Guidelines4/5

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

  The line 'Run before a cleanup sprint, not a targeted fix' explicitly states when to use and when not to use the tool, which is strong usage guidance. However, it doesn't name alternative sibling tools for targeted fixes, so the guidance is clear on timing/context but lacks explicit alternative routing.

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

• get_change_riskA
  4.6/5.0
  Behavior5/5

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

  With no annotations, the description carries the full burden and succeeds richly. It explains the comparison logic (findings reported only when the diff explains them), the meaning of health_delta.status=partial, scope counting, impacted_tests separation, prior_fixes semantics, and the idempotent include behavior. This is far beyond minimum disclosure.

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

  Conciseness5/5

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

  The description is long but every section earns its place: a front-loaded purpose statement, behavioral semantics, and then a clean Args list. Formatting is scannable, 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.

  Completeness5/5

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

  Given seven optional parameters, an output schema, and complex change-risk semantics, this description covers all invocation aspects, return field meanings, status interpretation, and edge cases like clean trees and skipped files. Nothing essential for correct selection or invocation is missing.

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

  Parameters5/5

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

  Schema description coverage is 0%, but the description compensates by explaining all seven parameters with concrete examples and behavioral details. revspec, repo, extensions, exclude_patterns, baseline, include, and finding_id each receive meaningful semantics beyond their schema types and defaults.

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

  Purpose4/5

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

  The description clearly identifies the tool's job: reviewing a commit, base..head range, or uncommitted work, and it details what the output leads with (directive, health_delta). It is specific about the resource and operation, though it never explicitly distinguishes this from the sibling get_risk, so the differentiation is inferred rather than stated.

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

  Usage Guidelines4/5

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

  It gives clear invocation context: how to pass revspec, when to omit it, how to control include modes, and how to expand findings. However, it does not say when to prefer this tool over alternatives like get_risk, nor does it state exclusions or 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.

• get_answerA
  4.8/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden and does so thoroughly. It discloses confidence tiers, evidence grounding, optional provider keys/network, fallback behavior, response size caps, reduction details, and recovery semantics. This is far beyond a basic 'answers questions' statement.

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

  Conciseness5/5

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

  Although long, every sentence earns its place: purpose, confidence behavior, offline fallbacks, size limits, reduction recovery, and parameter semantics. The description is front-loaded with the core purpose and organized with clear sections; nothing is wasted.

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

  Completeness5/5

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

  The tool has 4 parameters, no annotations, and an output schema. The description covers purpose, usage scope, param meaning, behavioral guarantees, failure/recovery paths, and output constraints. There is no obvious missing information an agent needs to select and invoke it correctly.

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

  Parameters5/5

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

  Schema description coverage is 0%, yet the description's Args section adds meaningful semantics for every parameter: 'question: Developer question', 'scope: Optional repository-relative path prefix', 'repo: Usually omitted; a workspace alias when needed', and 'include: Optional ["evidence"] expanded projection'. This compensates fully for the absent schema descriptions.

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

  Purpose5/5

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

  The description states a specific verb and resource: 'Answer a how, where, or why question in one evidence-grounded call.' This clearly distinguishes the tool from siblings like get_health or get_risk, which target different query types. The phrase 'how, where, or why' anchors exactly when this tool applies.

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

  Usage Guidelines4/5

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

  It gives clear context on when to use the tool for how/where/why questions, and it excludes general change-risk/health/overview concerns implicitly. It does not explicitly name sibling alternatives or state 'when not to use this vs. X', but the question-type framing is strong enough to guide selection.

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

• get_healthA
  4.8/5.0
  Behavior5/5

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

  With no annotations, the description carries the full burden, and it reveals key behaviors: read-only over stored data, dashboard vs ranked-file modes, 'unmatched ones land in unresolved, surviving only', 'only' alias/filter effects, and the exclusive nature of opportunity_id. This goes well beyond a generic 'get health data' statement.

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

  Conciseness5/5

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

  The description is long but every sentence is information-dense and earns its place. It front-loads purpose and the most important behavioral caveat, then presents parameters in a consistent terse format that avoids filler for an 18-parameter tool.

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

  Completeness5/5

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

  For a highly complex tool with no annotations, this is remarkably complete: it discloses storage/read behavior, update prerequisite, special identifiers, view modes, filters, and fallback fields like unresolved and unknown_only_keys. Because an output schema exists, the lack of a return-format explanation is not a gap.

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

  Parameters5/5

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

  Schema coverage is 0%, but the description compensates by explaining every parameter: targets accepts file paths or module:<name>, include lists accepted facets and queue side-effects, only explains key persistence and aliasing, and the refactoring_/performance_ parameters describe projections and filters. The docs pointer 'docs/agent/MCP_TOOLS.md' also fills in accepted values.

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

  Purpose5/5

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

  The opening line 'Code-health scores and findings from stored analysis' names a specific domain and return type, and the next sentence sharpens behavior: 'No targets returns a dashboard; targets return ranked files and findings.' This differentiates get_health from sibling tools such as get_overview or get_risk by its health-analytics focus.

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

  Usage Guidelines4/5

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

  The description gives clear context: it reads stored analysis and 'Never recomputes health', with the explicit prerequisite 'commit changes, then run repowise update' when freshness is needed. It does not compare against sibling MCP tools by name, but the stored-analysis caveat is enough to steer an agent away from using this as a computational tool.

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

• get_overviewA
  4.9/5.0
  Behavior5/5

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

  With no annotations present, the description carries the full disclosure burden and does so thoroughly. It reveals compact-by-default output, the `more` field, char-limit behavior, `_meta` reduction reporting, and the "projections, not omissions" semantics for gated blocks. This gives an agent an accurate mental model of side effects, output shape, and cost implications 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.

  Conciseness4/5

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

  The description is front-loaded with its core value proposition and then organized into clear sections: returns, when-to-skip, default behavior, workspace modes, and args. It is long, but nearly every detail earns its place; minor redundancy exists between workspace mode bullets and the repo arg line, though this does not meaningfully hurt clarity.

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

  Completeness5/5

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

  Given an output schema exists and both parameters are thoroughly documented in prose, the description supplies all essentials: what the tool returns, how to request extras, how workspace scoping changes results, and how large payloads are managed. No critical operational information required to invoke or interpret the tool appears to be missing.

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

  Parameters5/5

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

  Schema coverage is 0%, but the description fully compensates with an Args section explaining repo as alias/path/ID and "all", and enumerating every include value with the exact block each one activates. The semantic meaning is far richer than the bare schema, which only says two nullable fields with defaults.

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

  Purpose5/5

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

  The description opens with a crisp job statement — "Architecture map for an unfamiliar repo" — and enumerates the concrete contents: overview summary, key modules, entry points, architecture layers, code health, and git health. It also distances itself from later-stage siblings by naming get_context / get_answer as follow-ups, so the tool's place in a workflow is unmistakable.

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

  Usage Guidelines5/5

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

  Usage is explicit: this is the "first call when you don't know your way around," and it should be skipped once the map exists in favor of get_context / get_answer. Workspace-mode behavior is fully specified for omitted repo, repo="all", and repo="<alias>", leaving no ambiguity about when each call shape is appropriate.

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

• get_riskA
  4.9/5.0
  Behavior5/5

  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 so thoroughly. It discloses that structural reach is not proof of runtime breakage, that structural_impact_score is uncalibrated and never a probability, that overall_risk_score is a deprecated alias, and that include-gated blocks are projections rather than omissions.

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

  Conciseness4/5

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

  The description is long, but every sentence adds a distinct fact and it is well structured with an opening purpose, signal definitions, PR-mode directives, caveats, response limits, and an Args section. It could be trimmed, but the density is justified for a tool with many behavioral caveats.

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

  Completeness5/5

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

  Given zero annotations, zero schema descriptions, and a complex response surface, this description is complete. It covers purpose, selection criteria, parameter semantics, response shape, size limits, recovery metadata, and safety caveats, leaving nothing essential for correct invocation unexplained.

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

  Parameters5/5

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

  Schema description coverage is 0%, but the Args section compensates by explaining all four parameters: targets as file paths, repo as usually omitted, changed_files as PR-changed files for blast-radius mode, and include as opt-in blocks with concrete values like 'graph', 'churn', and 'scales'. This fully covers the parameter semantics gap.

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

  Purpose5/5

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

  The opening line, 'What history says about touching these files — bug fixes, churn, owners,' states the tool's purpose with a specific verb and resource. It further clarifies by describing the fused signal types and explicitly distinguishing get_risk from get_change_risk, which handles commit/range scoring.

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

  Usage Guidelines5/5

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

  The description gives explicit when-to-use guidance: pass changed_files for PR mode, read the directive block first, and use get_change_risk instead for commits or base..head ranges. It also notes that repo is 'usually omitted,' giving the agent practical invocation context.

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

• get_contextA
  5/5.0
  Behavior5/5

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

  With no annotations, the description carries the full behavioral burden and meets it thoroughly. It discloses conditional fields (fix_history only on counted fixes, episodes only when records exist), the default no-source-bytes behavior, size limits, reduction counts with _meta.omitted recovery refs, _meta.recovery_unavailable storage failure, and explicitly clarifies that include-gated blocks are projections, not omissions.

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

  Conciseness5/5

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

  Although long, the description is dense with high-value information and well-structured: a headline, a returns paragraph, conditional behavior, batching advice, size limits, error signaling, and an Args block. Every sentence earns its place, and the core scoping statement is front-loaded.

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

  Completeness5/5

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

  The tool is complex with 4 parameters and no annotation support, yet the description covers target formats, include-block semantics, conditional fields, batching, output sizing, reduction recovery, and error indications. Since an output schema exists, returning to explain shell return values is unnecessary; 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.

  Parameters5/5

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

  Schema description coverage is 0%, so the description must fully compensate, and it does. It explains targets as file paths, module paths, or "path::Symbol" ids; enumerates all include block keys; defines compact's default and its effect; and clarifies repo is usually omitted. Every parameter receives meaningful semantics beyond the bare schema.

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

  Purpose5/5

  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: "Triage card for files / modules / symbols — relationships, not source bytes." It clearly enumerates what is returned (title, summary, signatures, hotspot bit, decision_record titles) and distinguishes itself from siblings like get_symbol, get_risk, and get_why without needing to inspect their schemas.

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

  Usage Guidelines5/5

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

  The description gives explicit routing guidance: "Either one is a cue to call get_risk," "get_why serves the bodies," and "Do not call get_symbol per signature." It also advises batching targets and using one call with include=["skeleton"] instead of reading files separately, covering both when and when-not to use alternatives.

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

• get_symbolA
  5/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It explains return contents, ambiguity resolution, fallback behavior for index misses, truncation/continuation handling, and depth semantics, all beyond what the bare schema shows.

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

  Conciseness5/5

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

  The description is dense but excellently structured: purpose and exclusions first, return behavior second, and a compact argument list. Every sentence adds value, and the not-an-entry-point warning earns its prominent placement.

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

  Completeness5/5

  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 annotations, and subtle modes like omission refs and depth expansion, the description covers use cases, routing, input formats, edge cases, and continuation handling. The output schema exists, so return-structure details need no extra explanation, but the description still provides them where relevant.

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

  Parameters5/5

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

  Schema description coverage is 0%, so the description must fully compensate, and it does. Every parameter is explained: symbol_id formats, context_lines bounds, repo's usual omission, query's restriction to omission refs, id alias, depth behavior, and reference usage.

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

  Purpose5/5

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

  The description names a specific verb and resource: a follow-up read of one symbol whose id was already provided by another response. It explicitly distinguishes itself from get_answer, get_context, and plain Read, so an agent can select it correctly without opening the schema.

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

  Usage Guidelines5/5

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

  The description states clearly when to use this tool: for elided bodies, continuations, or omission refs, not as an entry point. It names alternative tools and even warns against walking a file symbol by symbol, giving strong routing guidance.

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

• search_codebaseA
  5/5.0
  Behavior5/5

  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 so thoroughly. It explains mode routing heuristics, decision-record ranking, candidates semantics (up to limit, best first), and that some results are pages rather than files. It also notes that this result set is what to Read, providing context for downstream actions.

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

  Conciseness5/5

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

  The description is long but highly organized: a one-line summary, a clear usage-orientation paragraph, a mode-behavior paragraph, a candidates paragraph, and a terse bullet-style Arg list. No redundant fluff; every sentence adds value. The structured flow aids scanability.

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

  Completeness5/5

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

  Given the tool's complexity (7 parameters, multiple modes, output schema), the description covers usage boundaries, mode routing, filtering, return semantics, and integration with sibling tools. It is complete enough for an agent to select and invoke the tool correctly without additional context.

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

  Parameters5/5

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

  Schema coverage is 0%, but the description's Args section explains every parameter with meaningful details—e.g., page_type gives common valid values, mode enumerates auto|concept|symbol|path|hybrid. It compensates fully for the schema's lack of descriptions.

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

  Purpose5/5

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

  The description opens with 'Find code by concept, symbol, or path — hybrid codebase search,' specifying a precise verb and resource. It clearly distinguishes the tool from the sibling get_answer by framing it as the raw-hit retrieval tool rather than a question-answering tool.

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

  Usage Guidelines5/5

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

  Explicit guidance says to avoid this tool for factual questions ('call get_answer instead... searching first is a wasted round-trip') and directs use when 'you want the raw ranked hits themselves' or need to resolve symbol IDs or scope later get_context calls. This is concrete and actionable.

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