Server Quality Checklist

Tool Scores

• list_presetsB
  3.3/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'List', implying a read-only operation, and describes the scope of returned presets, but it does not disclose what happens when language is omitted, how results are structured, or whether any side effects exist.

  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 a single, focused sentence that front-loads the action and resource. It includes relevant examples in parentheses without wasting words.

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

  Completeness3/5

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

  The tool is simple with one optional parameter, but there is no output schema and no annotations. The description does not state the default behavior when language is omitted or what the returned list contains beyond 'presets', leaving some ambiguity for an agent.

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

  Parameters3/5

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

  Schema coverage is 100% and the only parameter has an enum plus a clear description ('restrict to one language'). The description's 'per language' phrasing adds little beyond the schema, 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.

  Purpose5/5

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

  The description states a specific verb ('List') and a specific resource ('audit query presets'), and adds useful scope: built-in versus user-provided, and per-language. This clearly distinguishes it from the sibling preset_search, which implies searching/filtering rather than listing.

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

  Usage Guidelines2/5

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

  The description mentions the language restriction but gives no explicit guidance about when to use this tool versus alternatives like preset_search or list_definitions. There are no when-to-use, when-not-to-use, or alternative-selection cues.

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

• find_referencesA
  3.5/5.0
  Behavior3/5

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

  With no annotations, the description carries the behavioral transparency burden. It usefully discloses the confidence-tier classification (exact, likely, name) and the side effect of automatic index building with a potentially slow first call. However, it does not state whether the operation is read-only, what the response structure looks like, or any other invocation side effects. The disclosed behaviors are helpful but incomplete.

  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 compact and front-loaded: it states the core function first, then the classification behavior, then the indexing caveat. Every sentence contributes meaningful information without redundancy. It is appropriately sized for the tool's complexity.

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

  Completeness3/5

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

  The description gives a solid mental model of what the tool does and how references are classified, but because there is no output schema and no annotations, the return format and exact result semantics are left unspecified. It lacks guidance on result ordering, how definition sites are marked, or how confidence tiers are represented. The description is adequate for a basic call but not fully complete for a tool with five parameters and no structured output documentation.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the description does not need to restate parameter meanings. The description adds context about indexing and confidence tiers but does not explain how individual parameters like limit, offset, or file affect behavior beyond their schema descriptions. 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.

  Purpose4/5

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

  The description clearly specifies the operation: returning occurrences of an identifier across the indexed workspace while marking definition sites. It distinguishes itself from definition-focused siblings by emphasizing references and definition marking, though it does not explicitly name alternative tools. The title reinforces the action with 'Find identifier occurrences'.

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

  Usage Guidelines3/5

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

  The description implies usage context: use this when you need all occurrences of an identifier in the indexed workspace, including definition sites. It provides some operational guidance by noting that a missing index is built automatically on first call, but it does not explicitly contrast with siblings like go_to_definition, callers, or ast_search. No when-not-to-use or alternative-routing guidance is given.

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

• preset_searchA
  3.6/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden. It discloses the output type ('capture hits with line numbers'), which is useful, but it does not mention side effects, whether an index is required, or error behavior. Since this appears to be a search-like tool, the lack of an explicit read-only hint or prerequisite note leaves some behavioral gaps.

  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 a single, compact sentence that puts the main verb and resource first and includes a useful pointer to list_presets. Every word earns its place with no repetition or filler.

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

  Completeness4/5

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

  For a 3-parameter tool with 2 required params, no output schema, and no annotations, the description provides a clear action and output expectation. It also points to list_presets for discovering valid preset names. Missing details like prerequisites or error cases are minor given the schema already documents parameters and the tool is straightforward.

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

  Parameters3/5

  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 a little by connecting 'named preset' to the name parameter and 'source file' to file, but it does not explain the 'language' override beyond the schema's own description. The schema carries the parameter semantics, so no additional compensation is needed.

  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 verb 'Run' and the resource: a named preset against a source file, with a specific outcome: 'capture hits with line numbers.' It distinguishes itself from list_presets by saying 'see list_presets,' implying that this tool executes a preset rather than listing them. It does not explicitly name what it is not compared to siblings like ast_search, but 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.

  Usage Guidelines3/5

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

  Usage is implied: to run a named preset, you use this tool. The reference to 'see list_presets' hints at a workflow of choosing a preset first, but there is no explicit statement of when to use this tool versus alternatives such as ast_search or find_references. No exclusions or when-not-to-use guidance is provided.

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

• ast_searchA
  3.9/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the behavioral burden. It discloses that the operation is a query that 'returns captures with line numbers,' which implies read-only behavior. However, it does not mention whether the file must be indexed, how language inference works, or what errors may occur — relevant gaps given the sibling index-related tools.

  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 two sentences with no filler. The first sentence front-loads the action and output; the second sentence states the appropriate use case. Every word contributes to understanding the tool.

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

  Completeness3/5

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

  The core call pattern is covered: file, query pattern, and captures with line numbers. However, with no output schema or annotations, the return shape and preconditions such as indexing requirements or language behavior are underspecified. The rich schema helps, but the description alone is not fully self-sufficient for an agent.

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

  Parameters3/5

  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 slightly enriches the pattern parameter by calling it an 'S-expression pattern,' but it adds no additional meaning about file path, language override, limit, or offset beyond what the schema already provides.

  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 operation: 'Run a tree-sitter query (S-expression pattern) against a source file and return captures with line numbers.' It clearly identifies the resource (source file), the action (AST query), and the output (captures with line numbers). It also frames itself as 'AST-shaped matching' distinct from Grep, which differentiates it from generic search tools.

  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 explicitly says when to use the tool: 'Use for AST-shaped matching that Grep cannot express.' This gives a clear context and an implied exclusion for simpler text searches. However, it does not compare against sibling code-intelligence tools like find_references or list_definitions, leaving some selection ambiguity within the tool suite.

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

• list_definitionsA
  3.9/5.0
  Behavior3/5

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

  With no annotations, the description carries the behavioral disclosure burden. It discloses the output fields (name, kind, line ranges) and frames it as non-whole-file reading, but it does not mention language inference behavior, possible limitations, error cases, or how the tool determines definitions. This is adequate but not richly transparent.

  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 two sentences, front-loading the core function and output details before adding the structural-alternative context. Every phrase earns its place, with no filler or repetition.

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

  Completeness3/5

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

  For a simple list tool, the description is mostly complete: it states the resource, output shape, and purpose. However, it lacks context about language inference/override behavior, unsupported languages, and return format nuances. With no output schema, a bit more detail about how the tool behaves would make it fully complete.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the parameters 'file' and 'language' are already documented in the schema. The description adds no extra parameter-level detail, such as the meaning of the language override or its enum values, which keeps it at the baseline of 3.

  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 uses a specific verb ('List') and identifies exactly what is returned: definitions in a source file with name, kind, and line ranges. It also gives concrete examples (classes, functions, methods) and distinguishes itself as a structural alternative to reading the whole file, separating it from content-reading tools.

  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 provides a clear usage context: use this tool to get a structural overview instead of reading the entire file. It does not explicitly enumerate exclusions or compare against sibling tools like ast_search or read_definition, but the intended scenario is reasonably clear.

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

• get_node_typesA
  4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It implicitly signals a read-only operation through the verb 'List' and tells the agent what will be returned, but it does not explicitly disclose side-effect profile, return format, or any prerequisites around file versus language selection.

  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 a single focused sentence that front-loads the resource being listed and adds a practical usage note. Every clause earns its place; there is no filler.

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

  Completeness4/5

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

  For a simple read-only listing tool with two well-described optional parameters and no output schema, the description conveys the purpose, the returned content, and the primary usage context. It lacks explicit return formatting details, but the schema already explains the parameter alternatives.

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

  Parameters3/5

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

  Schema description coverage is 100%, with both 'file' and 'language' already described in the input schema. The description itself adds no parameter-level detail, so the baseline 3 applies.

  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 resource — 'named node types, anonymous tokens and field names' — with a clear verb, 'List'. The clause about writing 'correct ast_search query patterns' ties it to a concrete use case and differentiates it from the sibling ast_search tool.

  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 explicit context: use this tool before ast_search to avoid trial and error. It does not explicitly state when not to use it or name alternative tools, so it falls just short of full exclusion guidance.

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

• calleesA
  4.2/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 it well: it discloses the heuristic/name-based nature, confidence tiers, grouping of same-named callees with `resolved_to` for disambiguation, and the side effect of automatically building a missing index. These are non-obvious traits an agent needs before calling.

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

  Conciseness5/5

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

  The description is two dense sentences with no filler. It front-loads the core behavior, then adds the ambiguity caveat, filter options, and index auto-build behavior — every clause earns its place.

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

  Completeness4/5

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

  The description covers output grouping, result fields, disambiguation, filters, and index auto-build — solid for a tool with no output schema. It does not state whether `limit`/`offset` apply to grouped callee names or individual call sites, nor the result ordering, which is a minor but real gap for pagination.

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

  Parameters3/5

  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 only light parameter context ('optional file/language filters', 'name-based'), which does not materially go beyond the existing schema descriptions for `name`, `file`, `language`, `root`, `limit`, and `offset`.

  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 the exact resource ('call sites inside a function's body'), the operation ('grouped per callee name'), and the direction of the query. 'Callee' and 'called by a function' make it clear this returns outgoing calls, distinguishing it from inverse siblings like `callers` and `find_references`.

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

  Usage Guidelines3/5

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

  The description gives clear context — inspect call sites inside a named function's body — and mentions optional file/language filters. However, it never explicitly says when to prefer this over sibling tools such as `callers`, `find_references`, or `list_definitions`; the contrast is only implied by the word 'callee'.

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

• delete_indexA
  4.2/5.0
  Behavior5/5

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

  No annotations are provided, so the description carries the full burden. It clearly discloses that the tool removes the index from the current session, deletes persisted cache files (SQLite db / JSON), forces a rebuild from scratch, and leaves source files untouched. This precisely defines the destruction scope and side effects.

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

  Conciseness5/5

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

  Two focused sentences. The first front-loads the action and its consequences; the second covers parameter usage and a safety caveat. There is no filler or repeated schema content.

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

  Completeness4/5

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

  For a one-parameter delete operation with no annotations or output schema, the description covers purpose, parameter behavior, side effects, and safety. It does not mention error handling for unknown roots or the effect on index_status, but these are minor gaps for a tool of this simplicity.

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

  Parameters3/5

  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 an explicit 'omit root when exactly one index exists' rule and reinforces the several-indexes requirement, but this is largely a restatement of the schema's 'required when several indexes exist'. The extra guidance is marginal but not redundant.

  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 'Drop' and a precise resource: 'a workspace symbol index built by index_workspace'. It clarifies what is removed (session index and persisted cache files) and differentiates itself from the sibling index_workspace by describing the rebuild cycle.

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

  Usage Guidelines3/5

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

  It gives conditional guidance for the root parameter ('Omit root when exactly one index exists; with several indexes you must pass root') and clarifies non-destructive scope, but it does not explicitly name alternative tools or state when to prefer this over other index-related operations. The usage context is implied rather than fully explicit.

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

• go_to_definitionA
  4.2/5.0
  Behavior4/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 deliberately disloses the key side effect: 'If the index for root does not exist yet it is built automatically (first all may be slow).' It also reveals proximity ordering behavior. It stops short of describing return shape or failure modes, but the most consequential behavior 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.

  Conciseness5/5

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

  Two sentences: the first front-loads purpose and scope, the second adds the critical performance caveat. Every word earns its place; no fluff, no repetition of schema content.

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

  Completeness4/5

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

  For a 5-parameter tool with no output schema and no annotations, the description covers scope, ordering, and the auto-index side effect, and the schema fully documents all parameters. It lacks an explicit statement of the return format and no-match or multi-index error cases, but the go-to-definition mental model is well supported.

  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 coverage is 100% so the baseline is 3, and the description adds value beyond the schema: it ties the auto-index-build behavior to the root parameter and clarifies the ranking semantics of file ('nearest ... first'), reinforcing the schema's 'reference file for proximity ranking' with concrete behavior.

  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 operation — locating 'definition sites of a name across the indexed workspace' — with a clear scope and ordering rule. This distinguishes it from read_definition (which reads content), find_references (which finds usages), and list_definitions (which lists without a name filter).

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

  Usage Guidelines3/5

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

  The description implies usage context: proximity ranking via 'nearest to the optional file first' and an index-build caveat. However, with 14 siblings including closely related tools like read_definition, find_references, and ast_search, it never explicitly says when to choose this tool over an alternative 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.

• index_workspaceA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the full behavioral burden. It discloses persistence, SQLite versus JSON fallback, and the per-root additive behavior rather than replacement. It could also mention cost or idempotency, but what it says is genuinely informative.

  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?

  Three sentences, each earning its place: what the tool does, when to run it, and the important per-root indexing caveat. No filler or repetition of the title.

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

  Completeness4/5

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

  Given only two parameters, full schema coverage, and no output schema, the description provides sufficient context for correct invocation: purpose, workflow placement, storage behavior, and indexing granularity. A return-value note would improve completeness but is not essential for this side-effectful tool.

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

  Parameters3/5

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

  Schema coverage is 100%, so both root and maxFiles are already documented. The description adds only a modest clarification that root is the source directory being indexed; it does not meaningfully extend parameter understanding beyond the 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 clearly states a specific action and resource: parsing supported source files into a persisted symbol index. It also names the index contents (definitions, identifier occurrences, call sites), making it distinct from the read/search siblings listed.

  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 explicitly says to run the tool once before find_references / go_to_definition, which provides clear workflow context. It does not enumerate alternatives or conditions when not to use it, but the usage context is strong enough for an agent to select it appropriately.

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

• read_definitionA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the behavioral burden. It discloses the core behavior: exact-name lookup, returning all overloads/same-named definitions, and including line numbers. It does not cover error cases or return structure, but for a read operation the described behavior is substantial.

  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?

  Two information-dense sentences with no filler. The key constraints (exact name, source file, all overloads returned, line numbers) are front-loaded.

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

  Completeness4/5

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

  For a simple read tool with four well-documented parameters, the description covers what the tool returns and its matching behavior. It lacks an explicit note on behavior when the name is not found or the file is missing, but no output schema exists and the core contract is clear.

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

  Parameters3/5

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

  Schema coverage is 100%, so the parameters are already documented in the schema. The description reinforces file and exact-name lookup but does not add significant semantics beyond that baseline.

  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?

  States a specific verb ('Read'), a specific resource ('source code of one definition... from a source file'), and the exact-name constraint. This distinguishes it from siblings like list_definitions and go_to_definition because it returns code content rather than listings or navigation.

  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 clearly signals it is for retrieving a known definition by its exact name from a file, which is actionable context. It does not explicitly name alternatives or give when-not-to-use conditions, but the exact-name requirement implies the boundary.

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

• resolution_statsA
  4.2/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the behavioral disclosure burden. It communicates a read-only analytical purpose ('measure, not assert') and details what statistics are aggregated: confidence tiers, import resolution, and multi-file name definitions. It does not discuss error behavior or indexing prerequisites explicitly, but the 'over the indexed workspace' phrasing implies the required state.

  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 two sentences with no redundancy. The core action and output categories are front-loaded, and the final sentence adds concise usage guidance without padding.

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

  Completeness4/5

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

  For a tool with one optional parameter and no output schema, the description covers the main invocation context and the shape of the output metrics. It could be slightly more explicit about prerequisites such as needing a previously indexed workspace, but that is reasonably inferred from 'indexed workspace'.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the single 'root' parameter is already fully documented in the schema. The description does not add extra meaning about the parameter, but the baseline of 3 applies because the schema carries the burden adequately.

  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 uses a specific verb ('Aggregate') and identifies a precise resource ('resolution statistics over the indexed workspace'). It enumerates the specific kinds of metrics produced, which clearly differentiates it from sibling tools that operate on individual definitions or references.

  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 explicitly frames the tool as a measurement tool ('Use it to measure, not assert') and connects it to assessing cross-file navigation, which gives clear context for when to invoke it. It does not name alternative tools or explain when not to use it, but the aggregate-versus-individual distinction is strongly implied.

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

• index_statusA
  4.3/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the burden of behavioral disclosure. It clearly specifies what is reported and the fallback behavior when no root is supplied, which is valuable beyond the title. It doesn't explicitly state read-only behavior, but 'Report' implies a non-mutating operation.

  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 two sentences with no wasted words. It front-loads the core purpose, then efficiently covers the optional-parameter fallback behavior.

  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 simple status tool with one optional parameter and no output schema, the description is complete. It names the reported fields, covers the empty-parameter case, and gives enough context for an agent to invoke it correctly.

  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 100%, so the baseline is 3. The description adds extra meaning beyond the schema by explaining what happens when root is omitted: the most recently built index plus all available roots are reported. This is genuinely useful semantic context.

  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 uses a specific verb ('Report') with a clear resource ('current workspace index state') and enumerates concrete contents: root, version, totals, watcher active, pending dirty paths. This distinguishes it from sibling tools like index_workspace and delete_index.

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

  Usage Guidelines3/5

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

  The description implies when to use the tool by naming the state-report scope, but it does not explicitly state when to prefer this over alternatives or when not to use it. The 'Without root' clause gives conditional usage guidance for the parameter, not tool-vs-alternative selection.

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

• analyze_complexityA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It explains what the metric approximates, what counts as a decision point, and that results are sorted. It does not detail whether the file must be indexed or whether large files may be slow, but for a read-only analysis tool, this is reasonable.

  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?

  One efficient, well-structured sentence states the metric, the decision points, the scope, and the sort order. Every part adds information and no words are wasted.

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

  Completeness4/5

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

  For a tool with only two simple parameters and no output schema, the description covers the essential behavior. It could mention whether 'file' refers to a workspace-relative path or an absolute path, and could hint at the output shape, but those are minor gaps given the tool's simplicity.

  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 coverage is 100%, so the schema already documents the 'file' and 'language' parameters. The description adds value by clarifying that the file is a source file and that the analysis is per function, which is not stated in the parameter descriptions. The language enum is self-documenting.

  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 the tool computes approximate cyclomatic complexity per function in a source file, sorted worst first, and explicitly defines the formula. This makes the tool's purpose clear and distinguishes it from sibling tools like ast_search or find_references, which do different things.

  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 for use: analyzing a source file for complexity metrics, with an optional language override. It does not explicitly name sibling alternatives or give when-not-to-use guidance, but the context is specific enough that an agent can infer when to use it.

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

• callersA
  4.4/5.0
  Behavior5/5

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

  No annotations are present, so the description carries the full burden, and it delivers thoroughly. It discloses heuristic matching, the exact/likely/name confidence logic, that same-named methods are mixed, and that index creation happens automatically.

  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?

  Four dense sentences, each with a distinct job: core behavior, return fields and confidence, caveat about mixed methods, and filter/index behavior. The most important trait is front-loaded and there is no filler.

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

  Completeness4/5

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

  With no output schema, it describes what each hit contains and how confidence is determined, covering the essential return semantics. It could clarify how resolved_to appears in results or provide an example, but overall it is quite complete.

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

  Parameters3/5

  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 parameters. The description re-states file/language filtering and adds the resolved_to guidance, though resolved_to is not an input parameter, which introduces slight ambiguity.

  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?

  States a specific verb and resource: finds call sites of a function by name in the indexed workspace. It also distinguishes itself by describing the heuristic nature, confidence tiers, and the mixing of same-named methods, making it clearly different from precise reference tools.

  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?

  Provides clear context: use for name-based/heuristic call discovery, and filter by resolved_to when a precise call graph is needed. It also removes an index prerequisite by noting that the index is built automatically if missing, though it does not explicitly name sibling alternatives.

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