Server Quality Checklist

Tool Scores

• get_file_contextB
  3.4/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. It mentions what the output includes (functions, classes, imports, relationships) but lacks details on behavioral traits like performance, caching, permissions, or whether it is read-only. This is insufficient for a tool with no annotations.

  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 only two sentences, front-loading purpose and usage. Every word earns its place, with no unnecessary information. This is a model of conciseness.

  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 that an output schema exists and schema coverage is 100%, the description adequately covers the high-level purpose and what the tool returns. However, it could be more explicit about the output format and how it complements sibling tools, making it nearly complete but with room for improvement.

  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 baseline is 3. The description does not add additional meaning beyond the schema; it only says 'comprehensive context' without elaborating on parameters like detail or include_hints. Thus, no extra value is added.

  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 gets comprehensive context for a file, listing functions, classes, imports, and relationships. While it doesn't explicitly differentiate from all sibling tools like get_module_context, the mention of 'connect to the rest of the codebase' helps distinguish it from more specific tools like get_function_context.

  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 provides a clear context for use: 'when you need to understand what a file contains and how it connects to the rest of the codebase.' However, it does not mention when not to use it or suggest alternatives among the many sibling tools, which would improve guidance.

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

• find_related_codeA
  3.6/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 hints at preventing duplication but does not disclose whether the tool is read-only, its performance characteristics, side effects, or how it retrieves results. Minimal behavioral context.

  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 long, front-loading the core purpose and usage guideline. Every sentence adds value with no redundancy or filler.

  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 has 2 parameters, 0% schema coverage, and no annotations, yet the description is minimal. While it covers purpose and usage context, it lacks detail on behavior and parameter specifics. An output schema exists, so return values are partly covered, but the description does not fully compensate for missing schema and annotations.

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

  Parameters2/5

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

  Schema description coverage is 0%, meaning no parameter descriptions exist in the schema. The tool description does not explain the 'description' or 'max_results' parameters beyond their obvious semantics from the tool purpose. It adds little meaning beyond what the parameter names imply.

  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 the verb 'find' and the resources ('functions, classes, and files') related to a natural language description. It distinguishes from siblings like 'find_related_files' and 'get_call_graph' by specifying conceptual search over location-based retrieval.

  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 explicit guidance: 'Use this when you know WHAT you're looking for conceptually but not WHERE it lives.' This gives clear context for appropriate use, though it lacks explicit when-not-to-use or alternative tool references.

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

• find_related_filesA
  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 must cover behavioral traits. It mentions scoring symbols and grouping results, but does not discuss safety (e.g., read-only nature), permission requirements, or side effects. Some transparency is present, but gaps remain.

  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 only two sentences, both essential and front-loaded. Every sentence adds value without redundancy.

  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 its low complexity, explicit usage guidance, and existence of an output schema (so return values need not be explained), the description is fairly complete for the tool's purpose. Slight lack of behavioral details prevents a higher score.

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

  Parameters2/5

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

  Schema description coverage is 0% and the description only explains the 'description' parameter implicitly and mentions 'max_results' defaults. It adds minimal meaning beyond the schema, failing to compensate for the lack of parameter descriptions in 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 the verb 'Find', the resource 'files related to a natural language description', and the method 'by scoring symbols inside them'. It distinguishes itself from sibling tools like find_related_code and get_file_context by focusing on files and description-based search.

  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 tells when to use ('when you need to understand which files are relevant to a feature or concept'). However, it does not mention when not to use or provide alternatives among siblings, which would be beneficial.

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

• get_class_contextA
  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 full burden. It describes the output scope (methods, properties, inheritance chain, usages) but does not disclose any behavioral traits such as performance implications, side effects, or authorization requirements.

  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-loaded with the purpose, and contains no unnecessary words or redundancy.

  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 that an output schema exists, the description adequately covers what the tool returns. It mentions methods, properties, inheritance chain, and usages. However, it could hint at the detail parameter's effect, but the schema covers that.

  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 schema already describes all parameters (class_name, detail, include_hints). The description adds no additional meaning beyond what the schema provides, defaulting to a baseline score 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 specifies the verb (get), resource (class context), and specific components (methods, properties, inheritance chain, usages). It clearly differentiates from siblings like get_function_context and get_module_context by focusing on class-level context.

  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 states when to use the tool: 'when you need to understand a class's interface and where it is used.' However, it does not explicitly mention when not to use it or provide comparisons with sibling tools like get_call_graph or get_subclasses.

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

• get_dependency_graphA
  4/5.0
  Behavior3/5

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

  No annotations provided, so description carries full burden. It discloses bidirectional graph traversal up to depth, but lacks details on output format, performance implications, or whether it is read-only. Basic behavior is clear but deeper traits are omitted.

  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 concise sentences, front-loaded with action, no extraneous words. Every piece adds value.

  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 output schema exists and only two parameters, the description is largely complete. It covers purpose, usage, and basic parameters. Minor gap: does not explain the output structure, but output schema likely covers that.

  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 0%, so description compensates partially. It explains depth ('up to the specified depth') and implies symbol_name as the symbol of interest. However, it does not clarify what constitutes a symbol (e.g., function, class) or provide format examples.

  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 specific verb 'Get' and resource 'dependency graph for a symbol', clearly indicating bidirectional dependencies (depends ON and depends ON IT) and max depth. This distinguishes it from sibling tools like get_call_graph (limited to calls) and get_subclasses (hierarchy only).

  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?

  Explicitly states use case: 'understand the impact radius of changing a symbol.' Implicitly differentiates from siblings by focusing on full dependency graph. However, it does not mention when not to use or alternative tools for more specific tasks.

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

• get_project_skeletonA
  4.1/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 states that the tool returns file tree and statistics, but does not elaborate on the nature of the statistics or any behavioral traits like performance impact or read-onlyness. The description is functional but lacks depth.

  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 concise (two sentences) and front-loaded with the primary purpose. No extraneous information; every sentence serves a clear function.

  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?

  Given that the tool has three optional parameters and an output schema (though not shown), the description is somewhat minimal. It covers the high-level functionality but does not elaborate on what statistics are included or how the detail parameter affects the output. However, the output schema likely provides the necessary return value 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 coverage is 100%, so baseline is 3. The description does not add additional meaning beyond what the schema already provides for the three parameters (max_depth, detail, include_hints).

  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 the tool's purpose: 'Get the full project structure with file tree and statistics.' It also specifies to call it first when starting work, which distinguishes it from sibling tools that focus on specific files or modules.

  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?

  Explicitly advises to 'Call this first when starting work on a project to understand its overall shape, module layout, and code distribution.' This provides clear context for when to use this tool versus alternatives.

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

• get_unused_symbolsA
  4.1/5.0
  Behavior4/5

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

  With no annotations, the description bears full burden. It discloses analysis of caller index and import graph, and lists excluded false positives (dunder methods, handlers, etc.). This provides good transparency for a read-only tool.

  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 concise: four short sentences, each adding value. First sentence states purpose, second explains method, third lists exclusions. No unnecessary words.

  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 has an output schema (so return format need not be explained) and three simple optional parameters, the description covers purpose, method, and exclusions completely. It is adequate for an AI agent to understand and invoke the 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% with clear descriptions for all three parameters. The tool description does not add any additional meaning beyond the schema, so baseline 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 clearly states it finds functions and classes with zero inbound references (dead code detection). The verb 'find' and resource 'unused symbols' are specific, and it distinguishes from sibling tools like get_call_graph by focusing on dead code.

  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 for dead code detection but lacks explicit guidance on when to use versus alternatives. No 'when not to use' or alternative tool names are provided.

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

• set_projectA
  4.2/5.0
  Behavior3/5

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

  No annotations are provided, so the description bears full responsibility. It discloses that the tool sets a state affecting other tools, but does not mention validation, error handling, or persistence. This is adequate but not rich.

  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 sentences, front-loaded with purpose, then usage context and effect. No redundant information; every sentence serves a purpose.

  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 the tool's simplicity and the presence of an output schema, the description covers the essential aspects: what, when, and effect on other tools. It is complete enough for its complexity.

  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% with a clear description. The description adds that the path should be an 'absolute' workspace root, reinforcing the schema but not adding significant new meaning beyond it.

  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 'Set or change the project directory that Grafyx analyzes,' using a specific verb and resource. It distinguishes from sibling analysis tools by being the only one that sets the project context.

  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?

  Explicitly says to call when 'No project loaded' and explains that after calling, other tools work on the specified project. Also mentions re-calling to switch projects, providing clear when-to-use guidance.

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

• get_function_contextA
  4.3/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 mentions that if multiple matches occur, a disambiguation list is returned, and that 'file_path' uses substring matching. However, it does not disclose whether the tool is read-only, any required permissions, or performance characteristics. These gaps are notable for a tool operating on a codebase.

  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 concise and well-structured. It front-loads the main purpose in the first sentence, then covers specialized syntax, disambiguation, and usage context in subsequent sentences. Every sentence adds value with no redundancy or unnecessary detail.

  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 presence of an output schema (not shown but indicated) and 100% parameter description coverage, the description is complete for its complexity. It explains purpose, usage, and edge cases (multiple matches, file_path disambiguation) without needing to cover return values since the output schema handles that. The tool's domain (code context) is well-served.

  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 baseline is 3. The description adds meaningful context beyond the schema: it explains the 'ClassName.method_name' syntax for function_name and the substring matching behavior for file_path. This enhances the agent's understanding of effective parameter 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 clearly states that the tool retrieves comprehensive context for a function, including signature, parameters, callers, callees, dependencies, and docstring. It distinguishes itself from siblings by emphasizing breadth ('comprehensive') and blast radius, which is unique among sibling tools like get_call_graph or get_class_context.

  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 'Use this when you need to understand what a function does, who calls it, and what its blast radius is for modifications.' This is clear guidance. However, it does not explicitly state when not to use it or how it differs from specific siblings, which would strengthen the score.

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

• get_module_contextA
  4.3/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 does not disclose behavioral traits like side effects, auth needs, or rate limits. However, the read-only nature is implied by 'Get an overview' and no destructive actions are suggested.

  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-loaded with the primary purpose, and every sentence adds value. No wasted words.

  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 that an output schema exists, the description need not explain return values. It provides the zoom level context, usage guidance, and all parameters are documented in the schema. The description is complete for its purpose.

  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 tool description does not add additional meaning beyond what is in the schema parameters' 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 clearly states the tool's purpose: 'Get an overview of all symbols in a directory/package.' It distinguishes itself from siblings by specifying it's the intermediate zoom level between get_project_skeleton and get_file_context.

  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 explicitly says: 'Use it to understand what a package contains before drilling into specifics.' This implies when to use (intermediate analysis) and when not (use siblings for whole project or single file).

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

• get_call_graphA
  4.5/5.0
  Behavior4/5

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

  Discloses key behaviors: recursion up to specified depth, builtin filtering by default, disambiguation for duplicate names. No annotations provided, so description carries full burden.

  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?

  Front-loaded with purpose, then concise details. Every sentence adds value with no redundancy.

  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?

  Covers core purpose, edge cases (disambiguation), filtering behavior, and depth meaning. Output schema exists, so return format not needed. Complete for the task.

  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?

  With 0% schema coverage, description adds meaning for all parameters: function_name syntax and disambiguation, depth as recursion limit, include_builtins toggling filtering.

  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?

  Clearly states the tool retrieves a recursive call graph for a function, distinguishing it from sibling tools like find_related_code or get_dependency_graph. Mentions specific syntax and disambiguation.

  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?

  Explicitly says 'Use this to trace execution flow...' providing clear use case. Implicitly contrasts with alternatives, but doesn't explicitly state when not to use.

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

• get_conventionsA
  4.5/5.0
  Behavior4/5

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

  With no annotations, the description clearly states it 'detects and reports' – a read-only operation. Simple enough, no hidden behaviors. Could mention output format but output schema covers that.

  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 concise sentences. Front-loaded with purpose, then usage guidance. No wasted words.

  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 0 parameters and output schema, the description fully covers the tool's role and when to use it. No gaps.

  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?

  No parameters, so baseline per instructions is 4. Description adds no param info, unnecessary.

  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 specific verbs 'Detect and report' and clarifies the resource 'coding conventions'. It distinguishes from sibling tools like file context or dependency graph by focusing on style/conventions.

  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?

  Explicitly advises using it BEFORE writing new code to ensure consistency. Does not list alternatives but the context of siblings implies this is the go-to for conventions.

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

• get_subclassesA
  4.5/5.0
  Behavior4/5

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

  No annotations exist, so the description carries full burden. It explains recursive traversal up to a configurable depth, handling of ambiguous class_name definitions, and the response format (ambiguous flag, candidates). It does not explicitly state it's read-only, but the nature of the operation implies it. Overall, sufficient behavioral 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?

  Two paragraphs: first sets purpose and use case, second adds detail on depth and ambiguity resolution. Every sentence adds information; no fluff. Front-loads the primary action and context.

  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 complexity of recursive class hierarchy and ambiguity, the description covers key aspects: depth control, disambiguation via file_path, and response behavior. An output schema exists, so return values need not be detailed. The description is well-rounded and sufficient for the agent to use the tool 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 coverage is 100%, baseline is 3. Description adds value beyond schema: explains depth range (1=direct only), file_path usage with substring match restriction, and the candidates retry mechanism. This enriches the agent's understanding of how to use parameters effectively.

  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?

  Description clearly states it finds all recursive subclasses of a given class. It differentiates from sibling tools by specifying a concrete use case: understanding the impact of changing a class's interface. This makes the tool's purpose distinct and actionable.

  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?

  Explicitly tells when to use: to understand the impact of changing a class's interface. It also explains the ambiguity scenario and how to resolve it with file_path. However, it does not mention when not to use this tool or compare it to siblings like get_call_graph, which could be alternatives for related queries.

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

• refresh_graphA
  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 burden, and it delivers. It explains the incremental vs. full re-parse behavior, mentions mirror re-syncing on Windows-mount projects, performance (~seconds), and the automatic file watcher behavior. This is rich behavioral context beyond what any annotation would provide.

  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, front-loaded with the core purpose, then usage, then behavior. Every sentence earns its place, and there is no redundant or generic filler.

  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?

  Despite having no parameters and no annotations, the description fully covers the operation, usage scenarios, behavioral nuances (incremental vs. full parse), platform-specific behavior, and the fallback to the file watcher. An output schema exists, so return values do not need explanation. This is complete for the tool's complexity.

  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?

  The tool has zero parameters, so there is nothing to document. The baseline for 0-parameter tools is 4, and the description adds helpful context about when the tool applies, which 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 clearly states the tool's function: 'Bring the codebase graph up to date with the code on disk.' This is a specific verb+resource pairing that distinguishes it from the sibling tools, which are all read/query operations (e.g., get_file_context, get_dependency_graph). The purpose 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?

  It explicitly says 'Use this after making changes to the codebase, or if the graph seems stale.' It also provides an important usage caveat: 'Normally the file watcher handles this automatically on native projects,' which tells the agent when this tool may be unnecessary. This is strong when-to-use guidance.

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