xmp4 — Semantic code knowledge for your stack

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

With no annotations, the description carries the transparency burden. It discloses the core read behavior and the step-by-step navigation, but doesn't mention pagination, sort order, or result shape. No direct contradictions, but limited behavioral depth.

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

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

Two sentences, front-loaded with the primary purpose. Second sentence adds valuable navigation guidance. No redundant information.

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

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

For a moderately simple tool with a rich schema, the description covers the core purpose and provides usage guidance. It lacks output format details, but the schema already documents pagination and formatting parameters.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no additional parameter semantics beyond clarifying the meaning of 'callees' as 'methods called by.'

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

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

The description uses the specific verb 'Find' with the resource 'direct callees (methods called by) a symbol in a project,' clearly distinguishing it from sibling tools like xmp4_callers. It also explains the iterative usage pattern, removing ambiguity.

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

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

The description gives clear context: use to find direct callees and step-by-step navigation. It does not explicitly exclude alternatives or name sibling tools, but the usage context is unambiguous.

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

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

No annotations are provided, so the description carries the full burden. It discloses the core behavior (finding direct callers) and the ability to navigate iteratively. However, it does not describe the return format, pagination behavior, or potential edge cases (e.g., no callers, ambiguous symbols). The description is not misleading, but it lacks depth for a tool with no output schema.

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

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

The description is two sentences, front-loaded with the primary purpose. The second sentence adds a valuable usage hint without redundancy. Every word earns its place; no fluff or irrelevant details.

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

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

Given the tool has no output schema and no annotations, the description provides the essential context for initiating the tool (find direct callers, iterate). However, it does not explain what the results look like, how to interpret them, or how options like output_format or pagination affect the results. This leaves some gaps for an agent to fully understand the tool's behavior.

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

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

Schema description coverage is 100%, so all 7 parameters are already documented in the input schema with descriptions. The tool description adds no additional parameter-level meaning beyond the schema, so the baseline score of 3 applies.

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

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

The description clearly states the tool's purpose: 'Find direct callers of a symbol in a project.' The verb 'Find' combined with the specific resource ('direct callers of a symbol') and scope ('in a project') makes it unambiguous. It also distinguishes itself from sibling tools like xmp4_callees (which would be direct callees) and xmp4_usages (broader references).

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

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

The description provides clear context on how to use the tool iteratively: 'Navigate step-by-step by calling xmp4_callers again on interesting results.' This implies a workflow for exploring caller chains. However, it does not explicitly mention alternatives or when *not* to use this tool, so it stops short of a 5.

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

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

No annotations are provided, so the description carries full responsibility for disclosing behavior. It only states 'List external dependencies of a project' and omits any details about return format, pagination, potential side effects (e.g., network calls), or operational constraints. This minimal disclosure is insufficient for an agent to fully anticipate tool behavior.

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

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

The description is a single, front-loaded sentence with no wasted words, earning high marks for conciseness. However, it is so brief that it misses opportunities to add useful context (e.g., that it is read-only or supports pagination), so it is not a perfect 5.

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

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

Given the tool has 4 parameters, no output schema, and no annotations, the description needed to provide more operational context. The single-line description covers the core purpose but leaves out important behavioral and usage context that would help an agent fully understand the tool's role among its many siblings. The schema helps with parameters, but the description remains incomplete for a well-rounded tool definition.

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

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

The input schema covers 100% of parameters with descriptions, including a highly detailed explanation of the 'project' parameter's matching rules and fallback behavior. Since schema coverage is high, the baseline is 3, and the tool description itself adds no additional parameter meaning beyond what the schema already provides.

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

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

The description uses a specific verb ('list') and resource ('external dependencies of a project'), which clearly distinguishes it from sibling tools like xmp4_callees and xmp4_callers that focus on code relationships. However, it leaves 'external dependencies' somewhat ambiguous—unclear whether it means packages, libraries, or other modules—preventing a perfect score.

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

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

There is no guidance on when to use this tool versus alternatives. The description does not mention any exclusions, prerequisites, or comparisons to siblings, leaving the agent to infer usage solely from the tool name and purpose. The detailed 'project' parameter description in the schema aids invocation but not tool selection.

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

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

With no annotations provided, the description carries the transparency burden. It discloses key behavioral traits: server-side execution, reliance on an index, and tier-based restrictions (file_path required in free tier; file_glob only with XMP4_PREMIUM_GREP_WALK=true). It does not mention result format or rate limits, but the core constraints are well-covered.

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

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

Three sentences with no fluff. The primary action and resource are stated first, followed by tier constraints and alternative tool guidance. Every sentence earns its place, making it compact and readable.

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

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

For an 8-parameter tool with no output schema and no annotations, the description sufficiently explains core use cases, tier restrictions, and alternatives. It omits details like pagination behavior or result structure, but those are partially addressed in the schema. Overall, it provides enough context for an agent to decide when and how to invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining when file_path vs. file_glob should be used (free vs. premium) and that grep targets non-indexed text, which aids parameter selection and interpretation.

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

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

The description states a specific verb ('search') and resource ('indexed project source files') with a clear scope: server-side regex text search. It also distinguishes from sibling symbol-oriented tools by explicitly mentioning to prefer xmp4_tests_for/xmp4_usages for SCIP symbols, making its purpose unmistakable.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: use grep for text not indexed (comments, literals, config keys) and prefer symbol tools for SCIP symbols. It also clarifies free vs. premium tier usage (file_path vs. file_glob), giving clear context for caller decisions.

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

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

With no annotations, the description must carry the full burden. It discloses that the tool is a guide and that following it leads to learning the correct workflow. This is sufficient for a static, non-mutating guide tool. There are no hidden side effects or complex behaviors to disclose.

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

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

The description is a single, front-loaded sentence: 'Usage guide for xmp4 tools — read this first to learn the correct workflow'. Every word earns its place, no fluff, and the key action ('read this first') is immediately clear.

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

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

Given the tool's low complexity (no params, no output schema), the description is complete enough for an agent to know when and how to use it. It clearly signals the tool's role as an onboarding guide within a suite of sibling tools. It could mention what the guide contains, but that is not necessary for basic selection.

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

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

The tool has zero parameters, so per the rubric the baseline score is 4. The description naturally adds no parameter detail, but nothing is needed. The schema is empty and the description appropriately avoids inventing irrelevant information.

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

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

The description clearly identifies the tool as a usage guide for xmp4 tools with the directive to read it first. This distinguishes it from all sibling tools, which are specific functional utilities (e.g., xmp4_grep, xmp4_search). The purpose is unambiguous and actionable.

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

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

The description explicitly states 'read this first', which is a clear when-to-use instruction. It implies the tool should be consulted before using other xmp4 tools. However, it does not explicitly mention when not to use it or alternative tools, so it falls just short of a 5.

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

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

No annotations are provided, so the description carries the burden. The verb 'Get' implies a read-only operation, which is a basic transparency signal. However, it does not disclose any additional behavioral traits such as pagination behavior, potential large results, or error handling for missing projects or symbols, which would be useful but are not required for an obviously non-destructive get operation.

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

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

The description is a single sentence that is direct and free of filler. It front-loads the core purpose and provides just enough detail to identify the tool, earning every word.

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

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

Given seven parameters and no output schema, the description is notably incomplete. It does not set expectations about the return format (e.g., a list or tree), nor does it explain how optional parameters like docs, page, or output_format affect results. The one-line description is insufficient for an agent to confidently predict the tool's behavior beyond the basics.

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

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

Schema description coverage is 100%, with all seven parameters having descriptive text in the input schema. The description itself adds no parameter-level meaning beyond the schema, which correctly establishes a baseline of 3. The mention of 'base, interfaces, derived' describes output content, not parameter usage.

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

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

The description uses a specific verb 'Get' with a clear resource 'type hierarchy' and scope 'for a symbol in a project', explicitly listing components (base, interfaces, derived). This clearly distinguishes it from sibling tools like xmp4_info or xmp4_usages, which serve different purposes.

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

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

The description provides no guidance on when to use this tool versus alternatives such as xmp4_info or xmp4_outline. It simply states what it does without context or exclusions, leaving the agent to infer applicability from the name and description.

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

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

No annotations are provided, so the description carries full burden for behavioral disclosure. It only says 'get detailed information' without explaining what that includes, whether the operation has side effects, how pagination works, or what the return structure looks like. The schema hints at some behavior (e.g., page being ignored) but the description itself is opaque.

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

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

The description is a single under-specified sentence. While it has no fluff, it lacks essential context needed for the agent to use the tool effectively, making it under-specified rather than concisely informative.

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

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

Given the tool's complexity (7 parameters, no output schema, no annotations), the description is inadequate. It does not explain what the tool returns, how to interpret the output, or when to use it, relying entirely on the schema for behavioral context.

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

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

The schema description coverage is 100%, with detailed docs for all 7 parameters. The description adds no extra parameter semantics, so the baseline of 3 applies because the schema already provides comprehensive parameter meaning.

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

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

The description clearly states the tool retrieves detailed information about a symbol in a project, providing a specific verb and resource. However, it does not distinguish itself from siblings like xmp4_symbol_at or xmp4_search, which also deal with symbols, so it lacks sibling differentiation.

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

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

There is no guidance on when to use this tool versus alternatives. The description neither mentions exclusions nor references sibling tools, leaving the agent without context for selecting xmp4_info over other symbol-related tools.

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

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It does not state that this is a read-only operation, how pagination works, what the outline format contains, or how project resolution behaves. The only behavioral hint is that it returns 'all symbols', which is scant.

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

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

The description is a single, focused sentence with no filler. It is perfectly concise and front-loaded, stating the action and resource immediately. Every word earns its place.

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

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

Despite having 5 parameters and no output schema or annotations, the description gives only a minimal statement of purpose. It lacks any explanation of return value structure, pagination behavior, or relationship to sibling tools, making it incomplete for a tool with this complexity.

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

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

The input schema has 100% description coverage, including detailed semantics for the 'project' parameter. The description adds no additional parameter meaning, but the schema already provides thorough documentation, so a baseline score of 3 is appropriate.

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

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

The description 'Get outline (all symbols) for a file in a project' uses a specific verb ('Get') and resource ('outline for a file'), with 'all symbols' clarifying scope and distinguishing it from sibling tools that focus on individual symbols or relationships. It clearly conveys the tool's function.

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

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

No guidance is provided on when to use this tool versus alternatives like xmp4_symbol_at or xmp4_hierarchy. There is no mention of appropriate contexts, prerequisites, or exclusions, leaving the agent to infer usage from the tool name and schema alone.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only says 'Search and browse projects' without detailing pagination, read-only nature, result format, or how filters interact. The schema covers parameter details, but the description adds no behavioral context beyond a high-level verb.

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

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

Two sentences, front-loaded with the tool's purpose, followed by a clear usage directive. No wasted words; every part contributes to understanding the tool's role.

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

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

With no output schema and no annotations, the description should indicate what the tool returns (e.g., a list of projects). It doesn't. It provides good workflow guidance for discovering projects, but the lack of return-type and pagination details leaves a gap for an unannotated tool. Given the tool's simplicity, this is a minimal but adequate score.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's phrase 'by language and name' highlights the key filters (language, query/repo) but does not add new parameter-level details beyond what the schema already provides.

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

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

The description clearly states 'Search and browse projects by language and name' with a specific verb and resource. It distinguishes the tool as the entry point for discovery ('Use this first to discover projects'), setting it apart from sibling tools that operate on specific repos.

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

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

It gives explicit when-to-use guidance: 'Use this first to discover projects, then use other tools with the repo name.' This provides a clear usage sequence, but it does not name specific alternative tools or explicitly state when not to use it, so it falls short of a 5.

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

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

No annotations exist, so the description carries the burden. It only states the purpose and prerequisite, not behavior like pagination, result format, or error handling. For a search tool, it should at least hint at output characteristics.

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

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

Extremely concise: two short sentences. Front-loaded with the core purpose, no wasted words.

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

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

With 7 parameters, no annotations, and no output schema, the description is too sparse. It lacks information on return values, pagination, or error behavior. The schema covers params but the overall tool context is incomplete.

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

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

Schema coverage is 100%, with rich descriptions for params like 'project' explaining disambiguation. The description adds no extra parameter semantics beyond the prerequisite. Baseline 3 applies.

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

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

The description states 'Search symbols in a project' with a clear verb and resource. It distinguishes itself from text search (xmp4_grep) by focusing on symbols, though it doesn't explicitly contrast sibling tools.

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

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

It provides a clear prerequisite: 'Use xmp4_projects first to find the project identifier.' This tells the user when to use the tool and a necessary precondition. It doesn't mention exclusions or alternatives, but the context is clear.

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

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

With no annotations provided, the description carries the burden of indicating behavior. 'Get' implies a read-only operation, and the resource is non-sensitive server metadata. However, it does not mention any potential side effects, authentication requirements, or return format, leaving some gaps for a completely transparent assessment.

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

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

The description is a single, front-loaded sentence with no redundant words. It immediately conveys the tool's purpose and scope, earning a top score for conciseness.

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

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

For a parameter-free tool with no output schema, the description sufficiently explains the high-level return value (server information, version, capabilities). It is complete enough for an agent to decide when to use this tool, though it could provide more detail on response structure if needed.

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

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

The tool has zero parameters, so the schema covers everything. The description adds context about what information is retrieved (version, capabilities), which is useful. The baseline for zero parameters is 4, and the description meets that.

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

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

The description uses a specific verb 'Get' and identifies the resource as 'server information, version, and capabilities'. This clearly distinguishes the tool from sibling tools focused on code analysis (e.g., xmp4_callees, xmp4_grep).

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

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

The description makes it clear the tool is for retrieving server-level details, which is distinct from the other xmp4 tools that query source code relationships. However, it does not explicitly state when not to use this tool or name alternatives, so it falls short of a 5.

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

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

No annotations are present, so the description carries the full burden for behavioral disclosure. It only says 'Extract source code' and fails to mention output format, pagination, permissions, or potential side effects. The read-only nature is implied but not elaborated.

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

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

The description is a single, front-loaded sentence with no filler or redundant information. Every word contributes to stating the tool's purpose.

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

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

The schema is rich and covers all parameters, but the lack of an output schema and sparse description leaves gaps around return structure and advanced behaviors like pagination or format handling. It is sufficient for basic invocation but not fully complete for nuanced use cases.

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

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

The input schema has 100% description coverage for all parameters, including detailed guidance on project disambiguation and output format defaults. The description adds no parameter-specific semantics, but the schema already fully documents them, so a baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Extract') and identifies the resource ('source code for a symbol in a project'), making the tool's purpose clear and distinct from siblings like xmp4_info or xmp4_view. It leaves no ambiguity about what operation is performed.

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

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

The description provides no guidance on when to use this tool versus alternatives such as xmp4_info, xmp4_view, or xmp4_outline. It simply states the action without context, exclusions, or references to related tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the coordinate conventions (1-based line, 0-based column) and the core behavior (returns symbol covering position). This adds meaningful context beyond the schema.

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

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

Two sentences, front-loaded with the key phrase 'LSP-style position→symbol lookup.' Every sentence earns its place—purpose, coordinate details, and usage context are delivered without waste.

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

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

For a 4-parameter tool with no output schema and no annotations, the description is reasonably complete. It covers the purpose, coordinate semantics, and a usage scenario. It doesn't explain return format or error cases, but the core lookup behavior is sufficiently specified for a straightforward tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the coordinate bases already present in the schema (line 1-based, column 0-based) but doesn't add new parameter semantics beyond the schema.

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

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

The description clearly states the tool's purpose: 'LSP-style position→symbol lookup' with a specific verb and resource, explaining it returns the symbol covering a given cursor position. It distinguishes itself from siblings by referencing coordinate-based lookup and the specific use case after xmp4_outline/xmp4_view.

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

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

It explicitly says 'Use after xmp4_outline/xmp4_view when you know coordinates and want the canonical symbol,' providing clear context for when to use it. It doesn't mention explicit exclusions or alternatives, but the situational guidance is strong enough for a 4.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the filtering logic and language patterns, and indicates it returns only direct test callers, which is useful. However, it does not mention return format, error handling, permissions, or any potential side effects, leaving some ambiguity.

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

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

The description is a single dense sentence that efficiently conveys the main purpose and the language-pattern details. While the parenthetical structure is slightly cluttered, every detail contributes to understanding the tool's behavior, making it appropriately concise.

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

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

The description is rich enough for the tool's complexity, covering the core behavior and language-pattern nuances. While there is no output schema and the description does not explicitly state the return format, the name and description strongly imply a list of tests, and the schema handles pagination and formatting parameters.

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

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

The input schema has 100% description coverage for all 7 parameters, so the schema already documents each parameter adequately. The tool description adds no parameter-specific meaning beyond the overall purpose, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb 'Find' and resource 'direct tests that exercise a given symbol', and distinguishes it from sibling tools by focusing on test-file candidates with language-specific patterns. This makes the purpose unambiguous and distinct.

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

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

Provides clear context for when to use the tool (to find direct tests for a symbol) and includes detailed language-pattern rules that clarify its scope. However, it does not explicitly mention alternatives or when not to use this tool versus other call-discovery tools.

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

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

No annotations are present, and the description only states the basic action. It fails to disclose pagination behavior, output format (Compact vs Verbose), what 'docs' includes, or how the tool behaves when no references are found. This leaves critical behavioral traits undisclosed.

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

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

The description is a single, clear sentence that front-loads the action and subject. It is free of redundancy and wastes no words, making it appropriately concise.

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

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

Despite a rich schema, the description omits essential context for tool selection and invocation: it doesn't mention the relationship to sibling usage tools, the response structure, or important behaviors like pagination and output modes. With 7 parameters and no output schema, this sparse description is insufficient for a correct selection.

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

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

Schema description coverage is 100%, with detailed parameter descriptions (project prefix matching, page defaults, output formats). The description adds no extra parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb 'Find' and clearly identifies the resource ('all usages/references of a symbol') and scope ('in a project'). This distinguishes it from sibling tools like xmp4_grep (text search) and xmp4_search (symbol search) by focusing on reference tracking.

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

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

No guidance is provided on when to use this tool versus alternatives such as xmp4_callees, xmp4_callers, xmp4_grep, or xmp4_search. The only conditional hint appears in the schema's project parameter (about calling xmp4_projects), not in the description, so the agent gets no help choosing among related tools.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It mentions a key constraint: 'Hard cap of 500 lines per call.' It also clarifies the tool returns 'raw file excerpt,' implying it does no semantic interpretation. However, it doesn't explicitly state whether the operation is read-only (though 'Read' implies it) or what happens when the cap is exceeded. This is a minor gap.

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

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

The description is exceptionally concise: three short sentences, each earning its place. It front-loads the core purpose in the first sentence, provides usage direction in the second, and adds a critical constraint in the third. There is zero redundancy.

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

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

Given the tool's moderate complexity, no output schema, and no annotations, the description covers the essential context: purpose, when to use, and a hard constraint. The schema handles parameter details comprehensively. The only minor gap is that the return value format is not explicitly described, but 'Read a raw file excerpt' clearly implies the content returned. Overall, this is well-rounded for a focused read tool.

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

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

Schema description coverage is 100%, and the schema already thoroughly documents all four parameters (project, file_path, from_line, to_line), including defaults and the 500-line cap. The description provides no additional parameter-level semantics beyond what the schema already contains. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description clearly states the action ('Read a raw file excerpt'), the resource ('from an indexed project'), and the scoping method ('by line range'). It also distinguishes itself from siblings by mentioning xmp4_search, xmp4_outline, and xmp4_source explicitly, making it clear that this is the tool for reading raw line ranges, not for searching or outlining.

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

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

The description gives explicit usage context: 'Use after xmp4_search/xmp4_outline locates the region of interest, or to expand a truncated xmp4_source snippet.' This tells the agent exactly when to use this tool versus the named alternatives. It effectively conveys the intended workflow.

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