xmp4 — Semantic code knowledge for your stack

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

No annotations are provided, so the description bears full responsibility. It only states the core functionality without disclosing behavioral traits such as error handling when a symbol is not found, pagination behavior, or any prerequisites. This minimal disclosure is insufficient for confident tool invocation.

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 consists of two concise sentences that state the purpose and provide a usage hint. No extraneous words or redundant information is present.

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 output schema, and no annotations, the description lacks detail on result format and how to interpret output. It does not explain how parameters like page, file_path, or output_format affect behavior, leaving gaps for effective use.

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 all 7 parameters described in the input schema. The description adds no further parameter semantics beyond what is already in the schema, 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 verb 'find' and the resource 'direct callees (methods called by) a symbol in a project.' It effectively distinguishes the tool from siblings like xmp4_callers by specifying the direction of the call relationship.

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 a usage hint: 'Navigate step-by-step by calling xmp4_callees again on interesting results.' This implies iterative exploration but does not explicitly state when not to use the tool or mention alternatives like xmp4_callers for inverse relationships. However, the context is clear enough for basic guidance.

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

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

No annotations exist, so description bears full burden. It discloses the purpose (direct callers) and iterative use, but omits details like output structure, error handling, or performance characteristics. 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.

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

Two concise sentences, front-loaded with action, no fluff. 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?

With 7 parameters and no output schema, the description is minimal. It lacks details on return format, pagination behavior, or disambiguation strategies beyond the iterative hint. Adequate but 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%, so baseline 3. The description adds no parameter-specific meaning; it merely repeats the function name. No extra context 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 it finds 'direct callers of a symbol', which is specific and distinct from siblings like xmp4_callees (callees) and xmp4_usages (all usages).

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 suggests iterative use by calling again on results, providing practical guidance. However, it does not explicitly mention when to use alternatives or 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.

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

No annotations exist, so the description must disclose behavioral traits. The one-sentence description only states the purpose, omitting whether the operation is read-only, requires authentication, pagination details, or any side effects. This is a severe gap for a tool with 4 parameters.

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 extremely concise (5 words), effectively front-loading the core action. It is well-structured for quick parsing. A 5 would require slightly more detail without losing brevity.

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 4 parameters, no output schema, and no annotations, the description is insufficiently complete. It fails to describe return format, pagination behavior, error handling (e.g., multiple project matches as hinted in the project parameter description), or any side effects.

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, so the tool description does not need to repeat those. The schema already explains the project matching heuristic, pagination, and output format. However, the tool description adds no additional insight beyond the schema, earning a baseline 3.

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 ('list') and resource ('external dependencies of a project'). It is specific enough to distinguish from sibling tools like xmp4_callees (internal callers) or xmp4_grep (text search). A 5 would require specifying what constitutes 'external dependencies'.

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 (e.g., xmp4_callees, xmp4_search). It does not mention prerequisites, context, or when it should be avoided.

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 fully disclose behavior. It does so by describing the free and premium tiers, the environment variable toggle, and the server-side nature. It lacks details on error handling or rate limits, but for a search tool, this is sufficient.

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 only 3 sentences, front-loading the purpose and then providing tier and usage guidance. Every sentence adds value, no 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 complexity (8 parameters, no output schema, no annotations), the description covers the essential aspects: purpose, tier model, sibling differentiation, and project parameter usage. It could mention pagination behavior, but that's partly covered by schema. Overall, highly complete.

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 all parameters have descriptions. The tool description adds high-level context (tiers, environment variable) but does not provide additional detail beyond what the schema already offers for individual parameters. Baseline 3 is appropriate.

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

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

The description explicitly states a specific verb ('regex text search') over a well-defined resource ('indexed project source files'). It also distinguishes from sibling tools like xmp4_tests_for and xmp4_usages, making the scope clear.

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

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

The description provides explicit guidance on when to use this tool vs. alternatives: 'Prefer xmp4_tests_for/xmp4_usages for SCIP symbols — grep is for text not indexed (comments, literals, config keys).' It also explains free vs. premium tiers.

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

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

The description states that this tool provides a 'usage guide' and should be used to 'learn the correct workflow', indicating it is a read-only, informational tool. Since no annotations are provided, the description carries full burden and adequately conveys the non-destructive, educational 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, concise sentence that conveys the tool's purpose and usage guidance without any waste. It is front-loaded with the key term 'Usage guide' and immediately tells the agent to read it first.

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 that this tool has no input parameters, no output schema, and no annotations, the description is perfectly complete. It tells the agent everything needed: that it's a guide to be read first. Nothing is missing.

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

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

The input schema has no parameters, so the description doesn't need to explain any. The schema description coverage is 100%, and the task of a guide with zero params is inherently self-explanatory. The description adds no param info because none is needed.

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 explicitly states this is a 'usage guide' that should be read first to learn the correct workflow, clearly distinguishing it from other xmp4 tools. The verb 'guide' and the resource 'workflow' make the purpose immediately clear.

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

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

The description explicitly advises to 'read this first', providing clear guidance on when to use this tool (before other tools) to learn the correct workflow. This effectively guides the agent's usage order among sibling tools.

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

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

No annotations provided, and the description does not disclose any behavioral traits beyond the basic operation. It does not mention read-only status, side effects, rate limits, or output format limitations. The schema descriptions compensate for parameters but not for 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.

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

The description is a single sentence that succinctly states the tool's purpose. It is efficient, but could benefit from minimal structural improvements like a brief usage note.

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

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

For a tool with 7 parameters and no output schema, the description is insufficient. It does not explain what the output looks like, whether results are paginated, or how the optional parameters interact with the result. Given the complexity, more context is 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?

Schema coverage is 100%, and the parameter descriptions in the schema are detailed (e.g., project parameter with disambiguation, page_size with limits). The tool description itself adds no additional parameter meaning, so baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves a type hierarchy (base, interfaces, derived) for a symbol, which is a specific and distinct purpose among sibling tools like info, callers, etc. However, it does not explicitly differentiate itself from siblings.

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

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

No guidance on when to use this tool versus alternatives like xmp4_info, xmp4_outline, or xmp4_search. The agent is left to infer usage context without any when-to-use or when-not-to-use information.

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 provided, and the description is minimal—only states it gets info. No disclosure of side effects, authentication needs, rate limits, or what 'detailed information' entails.

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?

Very concise single sentence; front-loaded with the core action. Could expand slightly without becoming verbose, but efficient for its 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?

Despite 7 parameters and no output schema, the description is too brief. It doesn't explain what 'detailed information' includes, pagination behavior, or how parameters like docs or output_format affect results.

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 each parameter has documentation. The tool description adds no extra meaning beyond the schema, meeting the baseline for high coverage.

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

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

The description clearly states the tool gets detailed info about a symbol in a project, using a specific verb and resource. It distinguishes from sibling tools like xmp4_callees or xmp4_callers which focus on relationships, but doesn't explicitly contrast with xmp4_symbol_at or 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?

No guidance on when to use this tool vs alternatives like xmp4_symbol_at or xmp4_source. No prerequisites or exclusions mentioned.

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

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

With no annotations, the description bears full responsibility for behavioral disclosure. It does not reveal behavior like error handling (e.g., file not found), pagination mechanics (page/page_size parameters exist but are unmentioned), or output format details. The minimal description omits important 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.

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

The description is a single sentence with no extraneous words. It is front-loaded with the core action and resource, achieving maximal 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?

Given 5 parameters, no output schema, and no annotations, the description is incomplete. It omits information about pagination, output format options, error scenarios, and how this tool fits into the broader set of sibling tools. A more comprehensive description is warranted.

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% (all parameters have descriptions in the schema), so the baseline is 3. The tool description adds no additional meaning beyond the schema, but the schema itself is sufficiently detailed for most parameters. The description does not improve upon 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 action ('Get'), the resource ('outline (all symbols)'), and the scope ('for a file in a project'). It succinctly conveys the tool's purpose, distinguishing it from siblings like xmp4_symbol_at which targets individual symbols.

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_symbol_at, xmp4_grep, or xmp4_search. There is no mention of prerequisites (e.g., the file must exist in the project) or context for optimal usage.

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 transparency. It does not mention any behavioral traits like pagination behavior, authentication needs, or side effects. However, the input schema covers pagination with page and page_size, so the description's omission is partially mitigated by schema coverage. Still, additional context on return format or limits would improve transparency.

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 extremely concise: two sentences with zero wasted words. It front-loads the purpose and immediately follows with usage guidance. Every sentence is essential and 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 moderate complexity (5 parameters, all optional, no output schema, no nested objects), the description is largely complete. It explains the tool's role in a workflow and leaves parameter details to the schema. A minor gap is the lack of information about what the tool returns (e.g., a list of project objects), but since there's no output schema, the description could hint at the return structure. Overall, adequate.

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%, meaning every parameter has a description in the schema. The tool description adds no new parameter meaning beyond what's in the schema. Therefore, 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 purpose: to search and browse projects by language and name. It uses a specific verb ('Search and browse') and identifies the resource ('projects'). Among siblings like xmp4_repos and xmp4_search, this tool is distinguished as a project discovery tool.

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 tells when to use this tool: 'Use this first to discover projects, then use other tools with the repo name.' This provides clear workflow guidance and indirectly suggests when not to use it (e.g., after you have a repo name, use more specific 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 provided, so the description carries the full behavioral burden. It only mentions the prerequisite step. The input schema details project matching behavior, but the description lacks disclosure of traits like result format or pagination specifics.

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 – one sentence plus a note. Front-loaded with the key action. No wasted words, though slightly more context could be added without bloating.

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 7 parameters (2 required) and no output schema, the description is minimal. It does not explain return values or how results integrate with sibling tools. The schema covers pagination, but completeness is adequate but not thorough.

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 (e.g., project case-insensitivity). The description adds minimal extra value 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.

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

The description clearly states 'Search symbols in a project' – specific verb and resource. The mention of using xmp4_projects first distinguishes it from sibling tools that may need a project ID.

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

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

Explicitly says to use xmp4_projects first to find the project identifier, providing clear context. However, it does not state when not to use this tool or list explicit alternatives.

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 cover behavioral traits. It states what it returns (info, version, capabilities) but doesn't detail performance, rate limits, or side effects. With no annotations, more context would be beneficial.

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 short and direct, one sentence covering the purpose. It's appropriately sized for a tool with no parameters.

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 no parameters and no output schema, the description adequately explains what the tool does. However, for a server info tool, it could mention that it returns JSON or provide example fields to be more complete.

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 no parameters, and schema description coverage is 100%. The description adds context about the return data, which is helpful since there's no output 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 it retrieves server information, version, and capabilities. However, it could better differentiate from sibling tools like xmp4_info, which might overlap.

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 implies it's for getting general server details, but doesn't specify when to use it over similar tools like xmp4_info or xmp4_guide, nor explicit alternatives.

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 should disclose behavioral traits like error handling or return format, but it only states the basic function without any details on side effects or limitations.

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, efficient sentence that conveys the core purpose without any unnecessary 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?

Given the complexity (7 parameters, no output schema, no annotations), the description is too brief and does not provide enough context for an agent to fully understand the tool's behavior, such as how to handle ambiguity in project matching or symbol resolution.

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 meaning beyond the schema's parameter descriptions, which already define each parameter clearly.

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 ('extract') and the resource ('source code for a symbol'), effectively distinguishing it from sibling tools like xmp4_info or xmp4_symbol_at 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, nor does it mention prerequisites or context for correct usage.

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 notes that line is 1-based and column is 0-based, which is important behavioral detail. However, it does not mention error cases, permissions, or the exact output format. Basic behavioral transparency is present but not exhaustive.

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 core purpose, and each sentence adds necessary information. There is no redundancy or filler. It is highly concise and structured effectively.

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 simplicity of the tool and full schema coverage, the description is largely complete. It specifies inputs, coordinate conventions, and usage context. It does not describe the output format, but this is arguably implied by the purpose. A minor gap, but adequate for the tool's 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, so the baseline is 3. The description adds value by explaining the overall LSP-style lookup context and the coordinate system (1-based line, 0-based column). It also clarifies the default column value ('default 0 = beginning of line') beyond the schema's 'default null'. This extra context justifies a 4.

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 specifies the tool's purpose: LSP-style position→symbol lookup. It states the inputs (file_path, line, column) and the output (symbol covering that cursor position). It distinguishes from sibling tools like xmp4_outline and xmp4_view by referencing them as prerequisites.

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 usage guidance: 'Use after xmp4_outline/xmp4_view when you know coordinates and want the canonical symbol.' This tells the agent when to invoke the tool. It does not explicitly list when not to use it, but the context implies alternatives exist among siblings.

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 provided; the description adds behavioral context by detailing the language-specific file pattern filtering. However, it does not disclose potential side effects (likely none), authentication needs, rate limits, or what happens if no tests are found. It relies on schema for parameter details.

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?

A single, well-structured sentence that immediately conveys the primary purpose followed by supporting details (language patterns). No wasted words; front-loaded with key action.

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 7 parameters (2 required) and no output schema or annotations, the description covers the core functionality and file pattern logic. It lacks details on output format, pagination behavior, and error handling, but is sufficient for an agent to understand the main task.

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

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

Schema coverage is 100%, so all parameters are described in the schema. The description does not add further meaning to individual parameters beyond the overarching function. 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 clearly states it finds 'direct tests that exercise a given symbol', specifying the action (find) and resource (tests for a symbol). The language pattern examples distinguish it from sibling tools like xmp4_callees or xmp4_callers.

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 implies when to use (to find tests) but does not explicitly say when not to use or mention alternatives like xmp4_callers or xmp4_usages. The context of sibling tools and the filtering logic provide clear usage context.

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 full burden for behavioral disclosure. It only states the basic function, omitting critical details like whether it performs read-only operations, authorization needs, rate limits, or pagination behavior. The description adds minimal value beyond the name.

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 concise sentence with no wasted words. It is front-loaded with the core action. However, given the complexity of 7 parameters, a slightly more detailed description might be warranted, but redundancy is avoided.

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 output schema, and no annotations, the description is too sparse. It does not explain return values, pagination, or how to interpret results. A more complete description would mention output structure or common usage patterns.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds no additional meaning beyond the schema, such as clarifying the 'docs' parameter's purpose or the 'output_format' options. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: finding usages/references of a symbol. The verb 'find' and resource 'usages/references' are specific, and the context 'in a project' matches required parameters. This distinguishes it from siblings like xmp4_callers (which focuses on direct callers) and xmp4_grep (text search).

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

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

No guidance is provided on when to use this tool vs alternatives such as xmp4_callers, xmp4_grep, or xmp4_search. The description lacks exclusions, prerequisites, or context about when this tool is preferred.

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 provided, so description carries full burden. It indicates read-only operation and a line cap. However, it does not disclose potential rate limits, auth requirements, or error behavior on missing files. Adequate for basic transparency.

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, front-loaded with purpose, concise, no unnecessary words. Every sentence adds value.

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?

No output schema exists, so description could explain return format but doesn't. However, for a read tool with clear input constraints and siblings in the same domain, it is mostly complete. Might miss details on invalid project or file handling.

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 little beyond the schema, just referencing line range generally. No new parameter semantics or format details are provided.

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 reads a raw file excerpt by line range, and distinguishes from siblings by mentioning specific use cases after xmp4_search/xmp4_outline and to expand truncated xmp4_source snippets.

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

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

Provides explicit usage contexts: after search/outline or to expand truncated source. Mentions hard cap of 500 lines. Lacks explicit when-not-to-use guidance, but context is clear.

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