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

No annotations exist, and the description does not disclose side effects (e.g., file modification), permissions, or error cases. It only mentions supported file types, which is minimal for a write 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?

Two sentences with no wasted words. Front-loaded with the main purpose, followed by supported file types. Concise and effective.

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 covers purpose and supported files but lacks behavioral context (e.g., file modification, success/failure, usage of optional parameters like 'after'). Adequate but not complete for a code modification 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 description adds marginal value. It clarifies that the tool works across file types and for various models, but does not deeply explain parameters 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 action (add a field) and the target resources (model/class/interface), and lists supported file types, distinguishing it from sibling tools like edit_lines_in_symbol or insert_near_symbol.

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 insert_near_symbol or edit_lines_in_symbol. No exclusions or context provided, leaving the agent to infer 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 provided, so description carries full burden. It states the action but does not disclose whether the tool is read-only, what permissions are needed, rate limits, or output format. Minimal behavioral context beyond the check types.

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?

Single sentence with key information: action, file types, and check types. No fluff, front-loaded, 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 no annotations and no output schema, the description should provide more. It lists checks but does not explain what the tool returns (e.g., list of issues, counts). Adequate for a simple audit tool but leaves gaps about output and 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 coverage is 100%, baseline 3. Description adds some context (e.g., 'Raise for full audit' for max_issues, default for project) but does not elaborate on the meaning of each check beyond enum names. Additional value is marginal.

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?

Clearly states the action (audit) and resource (config files of specific types .env/.yaml/.toml/.json) and specific check types (duplicates, secrets, orphans). Differentiates from siblings as no other tool targets config file auditing.

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?

Implies usage for config file auditing but provides no explicit guidance on when to use this tool vs alternatives (e.g., get_env_usage). No exclusions or context for 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, the description fails to disclose behavioral traits like read-only status, side effects, or how cross-referencing works, which is insufficient for safe 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 is very concise, consisting of a single sentence that front-loads the main purpose without any 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 simple tool with one parameter and no output schema, the description covers the core functionality well but could mention return format or scope limitations.

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 description adds no extra meaning to the 'project' parameter 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 the tool audits Dockerfiles, listing specific aspects (base images, stages, exposed ports, ENV/ARG, cross-ref with config files), which is distinct from sibling tools like analyze_config.

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 the tool is for auditing Dockerfiles but provides no explicit guidance on when to use it vs. alternatives or any prerequisites.

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 carry the full burden. It only states the output is a narrative but does not disclose whether the tool is read-only, modifies data, has side effects, or requires permissions. This is insufficient for a tool that likely processes file data.

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 phrase, which is efficient but lacks structure. It front-loads the main purpose but omits important details. It is not verbose, but could be more informative without adding bulk.

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 (1 required) and no output schema or annotations, the description is incomplete. It does not explain what 'hotspots' or 'suggested type' mean, nor how the required parameter 'changed_files' should be formatted. The description fails to fully inform the agent for correct invocation.

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 75% description coverage (3 out of 4 parameters described with defaults). The tool description does not add any extra meaning beyond the schema. The 'changed_files' parameter lacks description in both schema and tool description, but overall baseline is 3 due to 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 generates a compact narrative for commits/reviews with stats, hotspots, and suggested type. It distinguishes from sibling tools which are mainly analysis or search tools, but could be more specific about the input and output.

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. The description implies it's for commit/review summaries, but does not mention any conditions, exclusions, or when not to use it.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It lists possible transforms but does not indicate whether the operation is read-only, whether it has side effects, what authorization is needed, or what the return value looks like. This leaves significant gaps.

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 very concise, consisting of a single line that lists the transform options. It is well-structured for a list, but could be more informative without losing conciseness. Every word serves a purpose, though the overall content is minimal.

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 3 parameters, no output schema, and no annotations, the description is insufficient. It does not explain what the tool returns, how to use the 'pattern' parameter with different transforms, or provide any usage examples. The description is too brief to fully guide an agent.

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 descriptions for transform and pattern (67% coverage). The description merely restates the transform options already present in the schema, adding no new information about parameters. It does not explain the 'id' parameter or provide context beyond what is already in 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 function: 'Aggregate over a capture' and lists specific transforms. It distinguishes from sibling tools like capture_get and capture_list, which have different purposes. However, it does not explain what a 'capture' is, leaving some 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 provides no guidance on when to use this tool versus alternatives such as capture_get, capture_search, or other siblings. It does not mention prerequisites or typical use cases.

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 indicates a read-only operation ('Read'), but lacks details on error handling, invalid ranges, or authentication. With no annotations, it partially meets the burden.

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 core purpose and range. It is front-loaded and avoids fluff, though it could be slightly more structured.

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 simple read tool with 3 parameters and no output schema, the description is adequate but minimal. It does not explain return format or behavior for edge cases, and has no annotations to compensate.

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 the baseline is 3. The description echoes the schema's parameter info without adding significant new meaning, only restating the range options.

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 'Read a capture' with clear range options, specifying the action and resource. It distinguishes itself from siblings like capture_list and capture_put.

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 such as capture_list or capture_search. The agent receives no context for 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?

No annotations provided. The description only states listing behavior; no disclosure of potential side effects, permissions, or output characteristics. Leaves significant behavioral gaps.

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

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

Extremely concise single sentence that is front-loaded. However, it may be too brief given the number of parameters and sibling tools.

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 4 parameters, no output schema, and multiple sibling capture tools, the description lacks essential context about what constitutes a capture, parameter effects, and return format. Incomplete for effective tool 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 only 25% (only 'limit' has a description). The tool description adds no parameter meanings, failing to compensate for the lack of schema descriptions for session_id, project_root, and tool_name.

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 lists recent captures with newest first ordering. However, it does not differentiate from sibling capture tools like capture_search or capture_aggregate.

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. Siblings like capture_search and capture_aggregate suggest different filtering/aggregation purposes, but no distinction is made.

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 labels the tool as destructive ('Delete'), but provides no additional behavioral details such as irreversibility, required permissions, or side effects. With no annotations, the description carries the full burden and falls short.

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. However, it is slightly cryptic and could benefit from a bit more clarity.

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 lacks details on return type, effect, and the contradiction between 'filter required' and schema having zero required parameters. Given no output schema or annotations, the description is insufficiently 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 description lists three filter dimensions (age, session, project) corresponding to the schema parameters, but adds no details about units, formats, or constraints. Schema description coverage is low (33%), and the description does not compensate.

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 ('Delete'), the resource ('captures'), and the filtering criteria ('by age/session/project'). It also indicates that a filter is required, which distinguishes it from list or get 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?

The description implies usage for deleting captures with filters, but does not explicitly state when to use this tool over siblings like capture_list or capture_search. No alternatives or exclusions are 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?

No annotations are provided, so the description must fully disclose behavior. It mentions writing to an FTS5 store and returning an id + preview, but omits critical details like side effects (overwriting?), idempotency, size limits, or authentication requirements. This is insufficient for a write 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 conveys the core purpose and return value concisely. While it could include more detail, it avoids unnecessary words and front-loads the 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 the complexity (6 parameters, nested objects, no output schema) and the family of sibling capture tools, the description is incomplete. It does not explain what 'preview' contains, how output is processed (e.g., truncation), or how parameters like 'meta' affect storage. The agent lacks sufficient information to use the tool correctly without external knowledge.

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 all 6 parameters with descriptions (100% coverage). The description adds no extra meaning beyond the schema, so it does not enhance parameter understanding. 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 action: 'Sandbox a verbose tool output to FTS5 store' and its output: 'returns id + preview'. This distinguishes it from sibling capture tools like capture_get, capture_list, etc., which retrieve or manipulate captures differently.

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 offers no guidance on when to use this tool versus siblings such as capture_search or capture_get. It does not specify scenarios (e.g., 'use when you want to store output for later retrieval') or exclusions.

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 fully disclose behavioral traits. It fails to state if the tool is read-only, has side effects, or any rate limits. The only behavioral hint is 'BM25 search,' implying a read operation, but this is implicit.

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—one sentence and a short result list. Every word adds value with no redundancy. It is front-loaded and easy to parse.

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 five parameters, no output schema, and no annotations, the description is insufficient. It does not explain what 'sandboxed tool outputs' are, how session_id and project_root affect the search, or what the search algorithm does beyond BM25. The agent lacks necessary context to use the tool correctly without additional assumptions.

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 60%, with descriptions for query, limit, and tool_name. The tool description adds no additional parameter semantics beyond what the schema already provides. It does mention return fields, which may hint at output but not parameters. Baseline 3 is appropriate given moderate 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 performs BM25 search across sandboxed tool outputs, which is a specific verb and resource. It also lists return fields (id, snippet, bytes). While it distinguishes from sibling tools like capture_list and search_codebase, it doesn't explicitly differentiate its scope from, for example, capture_aggregate or search_in_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?

The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or typical scenarios. Siblings like capture_get or search_codebase exist but the description does not help an agent choose between them.

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 fully cover behavioral traits. It fails to disclose that delete and prune are destructive, what side effects exist, or any prerequisites (e.g., permissions, required state). For a CRUD tool, this is a significant 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 very concise, front-loading the core purpose ('Unified checkpoint CRUD') and operation enum. Every word earns its place, though it could benefit from slightly more structure (e.g., grouping operations by type).

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 6 parameters, no output schema, and no annotations, the description is incomplete. It does not explain return values for list/compare, error states, or how operations like prune or compare work in practice. The tool's complexity demands richer 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?

Input schema has 100% description coverage for all 6 parameters, so the baseline is 3. The description adds no extra meaning beyond listing the operations; it does not explain parameter interactions or constraints 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 'Unified checkpoint CRUD' and enumerates all operations (create, list, restore, delete, prune, compare), making the tool's purpose and resource obvious. It distinguishes from sibling tools which focus on analysis, code, and project actions.

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 lists operations and their default (list), providing some usage hints. However, it lacks explicit guidance on when to use this tool versus sibling checkpoint-related tools (like capture_* or memory_*) and does not specify when not to use each operation.

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, and the description does not disclose behavioral traits such as side effects (e.g., data creation/overwrite), permission requirements, or what 'build' entails. The tool may modify state, but this is unstated.

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 (13 words) with no wasted information. It is front-loaded with the 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?

With 5 parameters and no output schema or annotations, the description lacks critical context about what a 'corpus' is, what the tool returns, and any constraints. It is insufficient 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?

The description summarizes the filter parameters (type, tags, symbol) but does not add detail beyond the schema. Schema coverage is only 40%, and the description fails to compensate with explanations of parameter format or constraints.

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 ('Build a thematic corpus') and specifies the filtering criteria (type, tags, symbol). While it distinguishes from sibling 'corpus_query' implicitly, it does not explicitly contrast them.

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 'corpus_query'. There is no mention of prerequisites, when-not to use, or context for 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?

No annotations provided, so description is the sole source. Only states formatting but doesn't disclose side effects (e.g., does it modify the corpus?), auth needs, or behavior on missing corpus. The term 'format' is vague.

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?

Single, focused sentence that front-loads the purpose. No redundant words or filler.

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, so description should clarify return format. It says 'markdown context + a question' but lacks specifics (e.g., structure, example). Error conditions not covered. Adequate for simple query tool but could be richer.

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?

All three parameters are described in the input schema (100% coverage). The description adds 'ready for answering' but no extra semantics like default project or constraints on question format. 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?

Description clearly states the action (format), resource (observations of a named corpus), and output (markdown context + question). Distinguishes from sibling corpus_build by specifying it operates on an already-built corpus.

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?

Implies usage after corpus_build, but no explicit guidance on when to use vs alternatives or when not to use. No mention of prerequisites like corpus existence.

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 must fully disclose behavior. It lists detected change types but omits important details: whether the tool modifies state (likely read-only), output format, performance implications, or dependencies (e.g., requires a Git repository). This leaves the agent uncertain about side effects and expected output.

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?

Single sentence, front-loaded with key information. No wasted words; every part adds value. Perfectly concise for the amount of information provided.

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 output schema, the description should hint at return values, which it does indirectly by listing detected change types. However, it lacks information on how results are structured (e.g., diff list, summary). For a tool with only 2 parameters and high schema coverage, the description is adequate but not fully 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 parameters are already documented. The description adds minimal value beyond the schema—it confirms the purpose but doesn't clarify parameter values beyond existing descriptions. Baseline 3 is appropriate as 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 tool detects breaking API changes against a git ref and enumerates specific types of changes (removed funcs/params, added required params, signature changes). It uses a specific verb ('detect') and resource ('breaking API changes vs a git ref'), and distinguishes from sibling tools like 'get_changed_symbols' or 'find_hotspots'.

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. The description does not mention when not to use it, prerequisites, or scenarios where other tools (e.g., 'get_changed_symbols') would be more appropriate. Implicitly, it is for comparing API versions, but lacks explicit 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?

The description notes the tool does not execute actions, providing safety insight. However, it lacks details on return format, potential side effects, or permissions needed, especially given no annotations are provided.

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 is front-loaded with the key purpose, containing no 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?

For a simple tool with one optional parameter and no output schema, the description adequately explains the core functionality. It could mention the output type but is sufficient.

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 covers the sole parameter fully (100% coverage), and the description adds no extra meaning or context for the parameter beyond the schema's description.

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 detects conventional project actions (tests, lint, build, run) from build files without executing them, which differentiates it from sibling tools like run_project_action.

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 usage for inspection before execution, but does not explicitly state when to use this tool over alternatives such as run_project_action or other detection 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 description must fully disclose behavioral traits. It only mentions 'string-replace' but omits mutation side effects, permissions, or return 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?

Single, front-loaded sentence with no waste; efficiently conveys core purpose and key differentiator.

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, description is incomplete. It lacks return value info and behavioral details for a 6-param mutation 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%. Description adds meaningful constraint that old_string must be unique within symbol unless replace_all=true, adding value beyond 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?

Description clearly states verb ('string-replace') and resource ('indexed symbol's body'), and distinguishes from sibling 'Edit' by noting symbol-scoped and no read first needed.

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?

Description implies comparison with 'Edit' but does not explicitly state when to use this tool vs alternatives or provide exclusions.

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 must disclose behavior. It mentions exclusions and that the header shows total, but doesn't cover performance, side effects, or whether it modifies code. 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?

Single sentence, front-loaded with key action and scope. No unnecessary words; every part 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?

No output schema, so description should clarify return format. It mentions total in header but not the body structure. Adequate for a simple audit tool but leaves some ambiguity.

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 parameter descriptions. The description adds value by explaining the 'max_results' header behavior and default, which goes beyond schema. Slightly above baseline.

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 performs a project-wide audit for unreferenced functions/classes, specifying exclusions (entry points, tests, route handlers). It distinguishes from sibling tools like find_symbol or get_functions by its specific dead code focus.

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 use for identifying dead code, but lacks explicit when-not-to-use or alternative tool suggestions. Context is clear, but no exclusions or comparisons are provided.

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, and the description does not disclose behavioral traits such as read-only status, side effects, or required permissions. The term 'Rank' implies a non-destructive query, but explicit confirmation is missing.

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 concise, consisting of a single sentence that conveys the core purpose. However, the use of vertical bars and parentheses makes it slightly cryptic, warranting a 4 rather than a 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?

Without an output schema, the description fails to explain what the tool returns (e.g., a ranked list of function names with scores). It also omits behavioral details like that it is read-only, leaving significant gaps for an agent.

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% coverage, providing a baseline of 3. The description adds value by noting that 'complexity' applies to all languages while 'allocation' and 'performance' are Java-specific, which is not captured in 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 ranks functions by hotspot kind, listing three specific categories. It uses a specific verb ('Rank') and resource ('functions by hotspot kind'), distinguishing it from diverse siblings like add_field_to_model or capture_list.

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 does not explicitly state when to use this tool vs. alternatives or when not to use. While the kind parameter suggests use cases, no guidance on exclusions or comparisons to sibling tools is provided.

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, and the description only gives a high-level purpose. It does not disclose behavioral details such as whether it runs synchronously, requires project context, or how impact is computed.

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 one concise sentence that directly conveys the tool's purpose without unnecessary words or 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 lack of an output schema and behavioral details, the description is insufficient for an agent to fully understand the tool's behavior and expected output, especially with four 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?

With 50% schema description coverage, the description adds context for 'changed_files' and 'symbol_names' by linking them to the tool's purpose. However, it does not fully compensate for the undocumented parameters.

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 'infer' and the resource 'pytest files likely impacted by changed files or symbols,' distinguishing it from siblings like 'run_impacted_tests' which executes tests.

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 usage when analyzing test impact but provides no explicit guidance on when to use this tool versus alternatives like run_impacted_tests, and no exclusions.

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 fully convey behavior. It mentions using Tarjan's algorithm, indicating a read-only analysis, but does not disclose performance implications, side effects, or output format details 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?

The description is a single, concise sentence that conveys the tool's purpose with no unnecessary words or repetition. It is well-structured and front-loaded.

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 of graph algorithms and the absence of an output schema, the description could provide more detail on the return format (e.g., list of cycles, nodes involved). It covers the core purpose but leaves room for better completeness.

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 its two parameters, so the description adds no extra meaning beyond what's already in the schema. The schema itself is clear on defaults and limits.

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 'detect', the resource 'import cycles', and the method 'Tarjan's algorithm' for finding strongly-connected components in the file-level import graph. It effectively distinguishes this tool from siblings like 'get_imports' or 'get_dependencies' by focusing on cycle detection.

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 the tool is for detecting import cycles but does not explicitly state when to use it over alternatives or provide exclusion criteria. No guidance on prerequisites or context is given.

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 fully discloses behavior: method performance characteristics, embedding triggering a ~2min reindex, parameter dependencies (min_lines applies to ast, min_similarity to embedding). It is honest about limitations and trade-offs.

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 that front-load the purpose and then provide key method distinctions. Every word is informative with 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?

While the description covers core behavior and parameter semantics well, it does not describe the output format (e.g., structure of duplicate groups) or error conditions. Given the absence of an output schema, this omission leaves the agent uncertain about what to expect from the response.

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 has 100% coverage, but the description adds value by cross-referencing parameters to methods (e.g., 'min_lines applies to ast', 'min_similarity for embedding'), explaining the embedding reindex side effect, and clarifying default thresholds (0.90 for min_similarity). This goes beyond the schema's parameter descriptions.

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 'Find duplicate functions' and distinguishes between two methods (AST and embedding), providing a specific verb-resource pair. No sibling tool overlaps with this exact purpose.

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 explains when to use each method (e.g., ast for copy-paste, embedding for conceptual clones) and mentions the embedding method reuses an index from search_codebase. However, it does not explicitly state when not to use the tool or suggest 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 must disclose all behavioral traits. It mentions result format on miss ('reports which kinds were searched') and default kinds, but does not cover other aspects like performance, side effects, or output structure for non-errors.

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, each adding value: first states purpose, second gives default behavior + customization, third describes miss feedback. 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?

Given 9 parameters, no annotations, and no output schema, the description is somewhat short. It hints at output ('file, line, signature') but doesn't detail the structure. For a non-trivial tool, slightly more detail on output and batch mode would improve completeness.

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 89%, so the schema already documents parameters well. The description adds minimal extra meaning beyond the schema, mainly the miss reporting behavior tied to kinds. 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 'Locate a symbol: file, line, signature, minimal preview', which is a specific verb and resource. It distinguishes from sibling tools like search_codebase by focusing on symbol definitions rather than general 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?

The description provides clear guidance on when to use this tool: for locating symbols, and how to customize with kinds. It lacks explicit exclusions or references to alternatives, but the default behavior and miss reporting give enough 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?

With no annotations provided, the description carries full transparency burden. It discloses the algorithm (BFS) and the goal (shortest path), but does not address side effects, read-only nature, or potential performance implications. Basic but not comprehensive.

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 wasted words. It starts with the core purpose immediately. Perfectly concise and well-structured.

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 (2 required, all with schema descriptions) and no output schema, the description covers the algorithm but lacks details like return format, typical use cases, or complexity hints. Adequate but not fully complete for a graph traversal 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 adds minimal extra meaning beyond the schema (mentions BFS algorithm), but does not elaborate on parameter behavior or format. The level parameter's schema description is already detailed.

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 purpose: 'Shortest dependency path between two symbols (BFS through the dep graph).' It uses a specific verb ('get') and resource ('dependency path'), and is distinct from sibling tools like get_dependencies or find_import_cycles.

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 usage (finding shortest dependency path) but does not explicitly state when to use this tool vs alternatives (e.g., get_dependencies). No exclusions or context for selection are provided, making it merely implied.

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 fails to disclose the output format (e.g., list of symbols, file counts), performance considerations, or any side effects. The phrase 'symbol-level summary' is ambiguous; an agent might not know what to expect.

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, which is concise but at the expense of necessary detail. It is front-loaded with the core purpose, but the lack of structure (e.g., no separate paragraphs for usage or output) reduces clarity.

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 and no output schema, the description should elaborate on what 'symbol-level summary' means and the nature of the output. It does not provide enough context for an agent to confidently invoke it, especially without examples or return structure.

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 each parameter has a description in the input schema. The tool description does not add significant meaning beyond clarifying the comparison base (worktree vs ref). Baseline 3 is appropriate as schema already documents the parameters.

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 indicates it provides a symbol-level summary of worktree changes or changes against a ref. The verb 'get' and resource 'changed symbols' are specific. It distinguishes from siblings like get_git_status (which is file-level) and build_commit_summary (which is commit-level), though not explicitly.

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 explicit guidance on when to use this tool versus alternatives. The description implies it's for understanding symbol-level changes but does not exclude cases better served by other tools like detect_breaking_changes or get_change_impact.

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 only states the function without disclosing behavioral aspects such as whether it is read-only, performance implications, required permissions, or handling of large dependency graphs. This is insufficient for an analysis tool.

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 short sentence that is concise and free of waste. However, it is perhaps too brief and could benefit from slightly more detail without harming 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 the complexity of impact analysis and the absence of an output schema, the description should provide more context about what the tool returns (e.g., list of symbols, count, severity). The current description leaves the agent guessing about the output format and additional 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 80%, and the description adds context by naming 'direct + transitive dependents', which loosely maps to max_direct and max_transitive parameters. However, it does not add meaningful new details 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 'Impact analysis: direct + transitive dependents of a symbol' clearly states the tool's purpose: analyzing the impact of a symbol by finding its direct and transitive dependents. It uses specific terminology and distinguishes from siblings like 'get_dependents' and 'find_impacted_test_files'.

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 does not provide any when-to-use or when-not-to-use guidance. It lacks mention of alternatives or context in which this tool is preferred over siblings, leaving the agent to infer 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, the description must carry the full behavioral burden. It only states 'List classes' with fields, but fails to disclose truncation behavior, default sorting, performance implications, or any side effects. The schema provides parameter details, but the description lacks essential 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 brief (12 words) but includes output fields in parentheses. It is not overly verbose, but could be improved by front-loading key information like the tool's filtering capability. No structural issues.

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 output schema, the description should explain return values and behavior. It only lists field names without format details, truncation markers, or hints about pagination. The presence of a `_truncated` marker is only in the schema description. For a tool with 5 parameters, this is insufficient.

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 the schema already documents all five parameters. The description adds no additional semantic value beyond the schema. It is baseline acceptable.

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 lists classes with specific attributes (name, lines, methods, bases, file). This distinguishes it from sibling tools like get_functions or find_symbol, but could be more precise about the scope (e.g., entire project).

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. The description does not mention when to prefer it over get_functions, find_symbol, or other listing tools, leaving the agent without context for decision making.

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 fully disclose behavioral traits. It only states the basic fetch action, omitting details about caching (force_full), error handling, or output format.

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, well-structured sentence that immediately conveys the tool's 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?

Given the tool has 10 parameters and no output schema, a single sentence is insufficient. It fails to explain return values, parameter dependencies, or the behavior of options like level or max_lines.

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?

Despite 70% schema coverage, the description adds no parameter meaning beyond what the schema provides. It does not explain the interplay between parameters like name, names, force_full, or the overall effect of options.

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 ('Fetch') and the resource ('class source body'), specifying it includes methods. This distinguishes it from siblings like get_function_source and get_classes.

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. With many sibling tools for source retrieval, the description lacks any comparative context or usage constraints.

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 fully disclose behavior. It mentions 'SQL-migration snapshot' but does not explain whether the tool requires a live database, reads from migration files only, or if it has side effects. Behavioral traits (e.g., idempotency, caching) are absent.

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?

Single sentence, front-loaded with key terms ('Condensed SQL-migration snapshot'), no redundant words. Every element (tables, cols, types, etc.) contributes to understanding the tool's output.

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 lists the output components comprehensively. For a read-only schema tool with 4 optional parameters, this is mostly sufficient. However, it lacks information about error conditions, performance, or whether the schema is extracted from migrations or a live database. Still, it covers the main 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?

All 4 parameters are described in the input schema (100% coverage). The description adds minimal extra meaning beyond restating the schema components. Baseline is 3 due to high schema coverage; no significant semantic enhancement from the description.

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 output: a condensed SQL-migration snapshot covering tables, columns, types, nullability, defaults, PKs, FKs, indexes, and RLS policies. This distinguishes it from sibling tools like 'get_full_context' or 'analyze_config', which focus on code analysis rather than database schema.

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 explicit guidance on when to use this tool versus alternatives. The description does not state prerequisites, limitations, or suggest tools like 'discover_project_actions' for broader context. The agent must infer usage from the tool name and description 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?

With no annotations, the description should disclose behavioral traits like read-only status, output format, or performance considerations. It only states directionality and provides no additional behavioral context beyond the core purpose.

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 that efficiently conveys the core purpose. However, it may be too terse, missing some useful context that could be added without becoming verbose.

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 5 parameters, no output schema, and no annotations, the description is incomplete. It does not explain the return format, the truncation behavior noted in the schema, or provide examples, making it harder for an agent to use effectively.

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 80% with most parameters already described. The description adds context for the required 'name' parameter by implying it refers to the symbol, but does not enhance understanding of other parameters like 'max_results' or 'depth' beyond schema defaults.

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 'outgoing deps of a symbol' and 'what X calls/uses (downstream)', which precisely defines the tool's function and distinguishes it from sibling 'get_dependents' (incoming 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 implies use for outgoing dependencies but provides no explicit guidance on when to use this tool versus alternatives like 'get_call_chain' or 'find_impacted_test_files', nor any conditions or exclusions.

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 disclose all behavioral traits. It adds that only direct references are returned (a key constraint). However, it does not mention performance, side effects, permission requirements, or return format. The description is adequate but incomplete.

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

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

The description is a single, concise sentence that front-loads the core purpose ('Incoming deps') and scope ('direct references only'). No unnecessary words or repetition.

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 5 parameters, no output schema, and no annotations, the description is minimal. It covers the basic function but lacks guidance on parameter usage, return format, and behavioral nuances. Considering the tool's simplicity, it is marginally 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?

Input schema has 5 parameters with 80% description coverage (4 of 5 have descriptions). The required parameter 'name' lacks a description, and the tool description does not clarify its format (e.g., symbol name vs. path). The description adds no extra meaning 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 'Incoming deps: who calls/uses X, direct references only' clearly states the tool finds incoming dependencies (callers/users) for a given symbol, and specifies it returns only direct references. This distinguishes it from sibling tools like 'get_dependencies' (outgoing) and 'get_call_chain' (recursive).

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 the tool is used to find who calls or uses a symbol, but does not explicitly state when to prefer it over alternatives like 'find_dead_code' or 'get_change_impact'. No exclusions or when-not-to-use guidance are given.

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 full disclosure. It does not mention that the tool is read-only, side effects, rate limits, or behavior when multiple identifier parameters are supplied. The aliasing (symbol, symbol_name) is not explained.

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, front-loaded sentence that concisely lists the bundle contents. No wasted words, immediately communicates 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?

Without an output schema, the description should describe the return structure more thoroughly. It lists components but omits output format or error scenarios. For a pre-edit tool, this is adequate but not fully comprehensive.

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 83%, so most parameter semantics are documented. The description adds little beyond listing components; it does not clarify how each parameter affects the bundle (e.g., max_deps limits). Baseline score 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: it provides a 'bundle' of information needed before editing, listing specific components (source, direct deps, callers, siblings, impacted tests). This is specific and distinguishes it from siblings that might only cover a subset.

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 use before editing but does not explicitly guide when to choose this over siblings like get_dependencies or find_impacted_test_files. No 'when not to use' or alternative tools are 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 must fully disclose behavior. It states the tool 'score functions by likelihood' and gives examples, but it does not mention whether it is read-only, requires specific permissions, or how scoring works. The behavioral disclosure is adequate but not comprehensive.

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, information-dense sentence that conveys the tool's purpose and scope without any fluff. Every word is necessary and 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?

The tool lacks an output schema, yet the description does not mention the return format (e.g., a list of functions with scores). This omission leaves the agent uncertain about the output, making completeness only moderate.

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 explains max_results and project adequately. The description adds no further parameter context, meeting the baseline for high-coverage schemas.

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 'score' and resource 'functions', clearly indicating it ranks functions by entry-point likelihood. It distinguishes from sibling tools like get_routes and get_functions by focusing on scoring rather than simple listing.

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 get_routes or get_functions. The description lacks context on appropriate scenarios or exclusions.

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 description carries full burden. It indicates the tool is a read-only analysis (shows usage) and names three file categories. However, it does not disclose typical behavioral traits such as performance on large codebases, auth/permissions needs, or whether results are aggregated. It is adequate but not enriched beyond minimal function.

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 long, front-loaded with the main action, and contains no extraneous information. It is efficient and scannable, though it could potentially add a brief note about the return format without significant bloat.

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 output schema, the description provides a minimal but sufficient overview of what the tool returns ('where it's defined, read, written'). For a simple cross-reference tool with only 3 parameters and no nested objects, this meets completeness needs. It does not explain result ordering or pagination, but that is acceptable for this complexity level.

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 all 3 parameters with descriptions. The tool description itself adds no extra parameter semantics beyond what the schema already provides. With 100% schema coverage, 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?

Description clearly states the tool's purpose: cross-referencing an env var across code, .env files, and workflow configs, showing where it's defined, read, written. It uses specific verbs ('cross-reference', 'shows') and a specific resource ('env var'), distinguishing it from sibling tools like search_codebase or find_symbol.

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?

Description implies when to use (when needing env var tracing across multiple file types) but does not explicitly state when not to use or mention alternatives among the many sibling tools. No exclusions or context about prerequisite conditions (e.g., environment setup).

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 full burden but only partially discloses behavior. It mentions classification by role but omits details like how imports are traced, whether the search is recursive, file type restrictions, or return structure. More context is needed for an agent to understand 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, concise sentence with no wasted words. It communicates the core purpose efficiently. However, it could be slightly more structured to separate the matching and classification aspects.

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 3 parameters, no output schema, and no annotations, the description is too minimal. It doesn't explain what 'feature keyword' means, how imports are resolved, what roles imply, or how results are sorted/limited. An agent may not have enough context to use the tool correctly.

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 67% coverage (keyword has no description). The description adds no parameter-specific details; it only says files are classified by role. For the keyword parameter, the schema doesn't explain its purpose, and the description doesn't compensate. The other parameters are somewhat documented in the schema but not enriched by the description.

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 returns files matching a feature keyword and traced imports, classified by role (core, test, config). It uses a specific verb 'get' and identifies the resource as feature files. This distinguishes it from sibling tools like list_files and search_codebase, though it could be more explicit about the concept of 'traced imports'.

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 usage guidelines are provided. The description does not specify when to use this tool over alternatives, what prerequisites exist (e.g., project must be active), or what types of queries are appropriate. An agent would need to guess the 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?

With no annotations, the description carries full burden but omits behavioral details like performance, auth needs, or side effects. Only states purpose.

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?

Single sentence with no waste; every word adds value. Front-loaded and efficient.

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?

Lacks output schema; description insufficiently covers return format or error scenarios. Agents may not know structure of returned data.

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. Description adds no extra meaning beyond schema parameter descriptions.

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 returns files imported by a given file ('outgoing file-level import edges'), distinguishing it from siblings like get_file_dependents (incoming).

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 explicit guidance on when to use vs alternatives such as get_dependents or get_imports. The context implies usage through name and description but lacks explicit instructions.

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?

Annotations are absent, so the description carries the full burden. It only states the output type without disclosing any behavioral traits like read-only nature, performance implications, or required permissions.

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 immediately conveys the tool's purpose. No fluff or 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 simple list tool with good schema coverage, the description is minimally adequate. However, it does not explain the return format, pagination behavior via 'max_results', or how 'project' is used, leaving some gaps.

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 already fully describes all three parameters (100% coverage). The description adds no extra meaning beyond what the schema provides, so 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 returns files that import a given file, specifying 'incoming file-level import edges'. It uses a specific verb ('get') and resource ('file dependents'), distinguishing it from siblings like 'get_dependents' by focusing on imports.

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 'get_file_dependencies' or 'get_dependents'. The description only states what it does, not when to prefer it.

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. It only hints at return content for different depths but does not disclose behaviors like read-only nature, rate limits, or constraints (e.g., max_lines default). Batch mode via the 'names' parameter is undocumented.

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 (one sentence) but it lacks structure and clarity. While brevity is valued, the sentence is cryptic and misses key details, making it less effective than it could be.

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 8 parameters, no output schema, and many sibling tools, the description is insufficiently complete. It does not explain batch mode, the 'mode' parameter, default values, or the purpose of other parameters like 'project' and 'max_lines'.

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 value by explaining the effect of the 'depth' parameter (deps/dependents vs. change impact) but does not clarify other parameters like 'mode', 'names', or 'max_lines' beyond what the schema already says.

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 it returns a 'Symbol bundle' with location, source, deps/dependents, and optionally change impact, indicating it provides comprehensive context about a symbol. However, it lacks an explicit verb (e.g., 'Retrieve') and uses jargon ('Symbol bundle'), slightly reducing clarity.

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 sibling tools like get_dependencies, get_dependents, or get_change_impact. It does not mention that it can replace multiple separate calls, nor does it give any usage context or exclusions.

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?

Discloses truncation behavior with _truncated marker, default behaviors for max_results, hints, and compress. Missing mentions of read-only nature or performance, but adequately covers key behaviors beyond empty annotations.

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?

Single, front-loaded sentence that captures the main purpose. Could be slightly more structured, but 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?

No output schema; description does not specify the structure of returned function entries (e.g., names, signatures, line numbers). Parameter descriptions help but return format is missing for complete agent usage.

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?

Input schema has 100% coverage with parameter descriptions. The description adds value by explaining the file_path vs all distinction and truncation behavior, going beyond schema defaults.

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?

Description clearly states the tool lists functions in a file or across the project, using specific verb and resource. It distinguishes from siblings like get_classes or find_symbol.

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 context for file_path vs project-wide use, but does not offer explicit when-to-use or when-not-to-use comparisons with sibling tools for symbol retrieval.

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 full burden for behavioral disclosure. It only states 'Fetch a function/method source body' but omits critical traits: is it a read-only operation? Does it have side effects? Are there performance considerations? Minimal information provided.

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 short sentence, which is concise. However, it is too brief for a tool with 10 parameters and no annotations. It could be expanded slightly without losing conciseness to cover key points.

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 (10 parameters, no output schema, no annotations), the description is severely incomplete. It does not explain the behavior of 'names' vs 'name', the 'level' parameter, or the 'hints' flag. The agent lacks sufficient context to use the tool effectively.

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 high (80%), so parameters are mostly explained in the schema. The description adds no additional meaning beyond the schema. 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 action ('Fetch') and the resource ('a function/method source body'), distinguishing it from siblings like 'get_class_source' or 'get_functions'. While clear, it could be more specific about what 'source body' entails (e.g., the code definition).

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. The description does not mention any context, prerequisites, or when not to use it, leaving the agent without decision support.

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; description does not disclose read-only behavior, side effects, or error conditions beyond the obvious git status 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?

Single sentence with all key info, no fluff, front-loaded.

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 simple tool with one optional parameter and no output schema, the description provides a list of output components, but lacks context like required git repo or behavior when no changes.

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 covers parameter completely; description adds no extra meaning beyond the schema's description. Baseline 3 due to 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?

Description clearly states verb ('get') and resource ('git status'), listing components (branch, ahead/behind, staged, unstaged, untracked), distinguishing it from 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?

No guidance on when to use this tool vs alternatives (e.g., build_commit_summary) or when not to use it. Only implied by name.

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 disclose behavioral traits. It only states the action and output fields, but fails to mention that this is a read-only operation, any required permissions, or how results are paginated or truncated. Critical context is missing.

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 (4 words) but is not a complete sentence. It is front-loaded and avoids fluff, but could benefit from rephrasing for clarity (e.g., 'Lists import statements including module, names, and line numbers').

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 4 parameters and no output schema, the description provides minimal context about the return format. While the schema covers parameter semantics, the tool lacks information on result ordering, truncation behavior (mentioned in max_results param), or how to interpret the output. It is functional but not fully 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% with each parameter described. The description adds no additional semantics beyond the schema, so a baseline of 3 is appropriate. The description does hint at the output format ('module, names, line'), which is not in 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 uses a specific verb 'List' and resource 'imports', and explicitly mentions the returned fields (module, names, line). This clearly distinguishes it from sibling tools like get_dependencies or get_file_dependencies, which deal with different aspects of code relationships.

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 (e.g., get_dependencies, get_file_dependencies). There is no mention of prerequisites or typical use cases, leaving the agent to infer usage from the description 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, and the description does not disclose any behavioral traits beyond the output content. It lacks details on error handling, performance, or whether it requires an active project.

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 that efficiently lists what the tool returns. No redundant or extraneous 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?

The description lists the kind of information returned but does not specify the structure or format (e.g., JSON keys). With no output schema, this leaves some ambiguity, but for a simple summary it is 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?

The input schema coverage is 100% and the single parameter 'project' has a description. The tool description adds no additional meaning beyond what the schema already provides, so 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 provides a project overview including specific items (file count, packages, top classes/functions, infra dirs). This distinguishes it from sibling 'get_' tools like get_call_chain or get_structure_summary by focusing on a high-level summary.

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 explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, limitations, or contrast with similar tools (e.g., get_structure_summary, get_full_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 are provided, so the description must disclose behavioral traits. The description implies a read-only detection operation but does not state safety (e.g., no modifications), required permissions, rate limits, or limitations. This lack of transparency leaves the agent uncertain about side effects and constraints.

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 of 15 words with no unnecessary details. It is front-loaded with the core purpose and fits the tool's simple nature perfectly.

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 tool has no output schema, so the description should partly explain return values, which it does (path, file, methods, type). However, it omits details on pagination, error handling, or behavior when the project is not found. For a simple detection tool with zero required parameters, the description is minimally adequate but lacks completeness.

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% coverage with clear descriptions for both parameters (max_results, project). The description adds value by explaining the output structure (path, file, HTTP methods, type), which compensates for the absence of an output schema. This helps the agent understand what information will be returned.

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 detects API routes and pages in a Next.js App Router project, specifying the returned information (path, file, HTTP methods, type). This is a specific verb+resource combination that distinguishes it from sibling tools that deal with functions, classes, or code 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?

The description provides clear context for when to use this tool (detecting routes in Next.js App Router projects) but does not explicitly state when not to use it or mention alternative tools. The guidance is implicit but sufficient given the tool's unique focus.

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?

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?

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?

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?

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?

Including how it differs from other get_* tools would improve clarity.

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?

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 mentions returning structure elements but fails to disclose that the tool is read-only or whether it has side effects. Given the context of file analysis, it is likely safe, but the description does not clarify.

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, clear sentence that front-loads the core behavior. No extraneous 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?

For a simple tool with two optional parameters and no output schema, the description is adequate but lacks details on the output format or depth of structure (e.g., recursive). It covers the basics but could 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?

Schema description coverage is 100%, with file_path already documented as 'Omit for project-level summary.' The tool description adds no new information beyond what the schema provides, so it does little to enhance understanding.

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 it returns 'Structure of one file (functions, classes, imports, line counts)' or project-wide if file omitted. It uses a specific verb and resource, and clearly distinguishes from siblings like get_functions or get_classes by offering a combined summary.

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 explicit guidance on when to use this tool vs. alternatives such as get_functions, get_classes, or get_project_summary. The description only states what the tool does, not when it is preferable.

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 full burden for behavioral disclosure. It only states 'Insert content before or after an indexed symbol,' which implies file modification but fails to mention side effects (e.g., potential code duplication, line shifting), required permissions, or whether the operation is reversible.

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 front-loads the core action. It avoids unnecessary words. However, it could benefit from additional structuring to separate intent from behavior.

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 (9 parameters, no output schema), the description is insufficient. It fails to explain what an 'indexed symbol' is, how to specify the insertion point (project, file), or expected outcomes. The agent lacks critical context for correct invocation.

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 67% of parameters with descriptions. The description adds no parameter-specific information beyond the schema. It mentions 'before or after,' which aligns with the 'position' parameter, but does not clarify the purpose of ambiguous parameters like 'file_path' or the multiple aliases for 'content.' A score of 3 is appropriate given moderate schema coverage and no value added.

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: 'Insert content before or after an indexed symbol.' It uses a specific verb and resource, and the phrase 'before or after' distinguishes it from sibling tools like replace_symbol_source or edit_lines_in_symbol which modify existing content rather than insert new content.

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. It does not mention any prerequisites, typical use cases, or exclusions. The agent must infer usage context from the tool name and siblings 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 carries full burden. It only implies a read operation ('list') but omits details like whether it returns full file contents, pagination behavior, permissions needed, or side effects.

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

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

A single efficient sentence front-loading the purpose. No superfluous words, but could be slightly more informative without losing 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?

Incomplete for a tool with 5 optional parameters and many siblings. Lacks explanation of return format, default ordering, effect of max_results=0, and how glob filtering interacts with indexed files.

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 minimal value beyond schema: it mentions aliases for pattern parameters but repeats the glob pattern explanation already in 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 'List indexed files, optionally filtered by glob,' which identifies the verb and resource. However, it does not differentiate from siblings like search_codebase or get_functions, which also list files or code elements.

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 (e.g., search_codebase for content search, get_classes for structural listing). No when-not or prerequisite 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?

The description implies a read-only, non-destructive operation through 'list', which is appropriate. However, it doesn't disclose error handling, empty results, or any permission requirements.

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, concise sentence with no superfluous words. Efficiently conveys 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?

For a simple list tool with no parameters and no output schema, the description covers the basic functionality. However, it could mention the structure of the output (e.g., list of project names with status fields).

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?

With zero parameters, the baseline is 4. The description doesn't add parameter-specific information, but 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 clearly states the verb 'list' and the resource 'all registered workspace projects', and adds a specific detail 'with index status'. This distinguishes it from sibling tools like get_project_summary.

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 (e.g., get_project_summary, list_files). The description provides no context about typical use cases or exclusions.

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 burden but only says 'single dispatch' and lists ops. It does not disclose destructive nature of ops like dedup_sweep or roi_gc, nor does it describe side effects, permissions, or error 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?

One sentence with no wasted words. Front-loaded with the core concept. Efficient and 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?

Despite simple schema, the tool has 21 sub-ops with varying behavior. No output schema. Description is too brief to cover what the tool returns or how each op behaves, leaving significant gaps for the agent.

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 covers 100% of parameters, but the description adds minimal value beyond examples for the 'op' parameter. It does not explain the purpose or behavior of each op, nor groups them. Baseline is 3 due to schema coverage, but description is too vague.

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 is a single dispatch for all memory admin/maintenance ops, listing examples. This is specific and distinguishes it from sibling tools like memory_get, memory_save, etc., which handle regular memory operations.

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 usage for admin/maintenance ops but does not provide explicit guidance on when to use it versus alternatives, nor does it list exclusions or prerequisites.

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?

Discloses that deletion is soft and sets archived=1, but with no annotations provided, it omits permissions, side effects, or return behavior. Adequate but not thorough.

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, precise sentence with no extraneous words. Every word contributes to understanding the tool's function.

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 simple delete operation with 2 parameters, the description covers the core action. However, it does not specify return value or confirmation, which would be helpful given no output schema.

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 description adds minimal value beyond the schema. The phrase 'sets archived=1' reinforces the id parameter's effect but does not exceed baseline expectation.

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 'soft-delete' and the resource 'observation by ID', with the specific mechanism 'sets archived=1'. It distinguishes from siblings like memory_get and memory_save.

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 (e.g., memory_admin or other deletion methods). No mention of prerequisites or when not to use it.

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

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

No annotations are provided, so the description must disclose behaviors. It mentions token count and progressive disclosure but does not confirm safe read-only operation, authentication needs, or side effects.

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

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

The description is very concise with two sentences, front-loading essential info. However, the phrasing 'Layer 3: full observation content by IDs (~200 tokens/result)' is somewhat cryptic without broader context.

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 output schema, the description should explain return structure but only mentions content and token count. It omits handling of invalid IDs, error cases, and result format, leaving agents underinformed.

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 already provides full coverage with descriptions for each parameter. The tool description does not add significant semantic detail beyond what the schema offers, 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 retrieves full observation content by IDs and positions it as the final layer in a progressive-disclosure system, providing a specific verb and resource with clear differentiation from other layers.

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 mentions 'progressive-disclosure layer' but does not explicitly state when to use this tool versus alternatives like memory_search or memory_list, nor does it provide criteria or exclusions.

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, and the description does not disclose any behavioral traits beyond the return format. It does not indicate whether the operation is read-only, if it has side effects, or any performance implications.

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 that efficiently conveys the purpose and return fields. 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?

Given the lack of output schema and annotations, the description is insufficient. It does not define 'recent', explain default entry count, list possible observation types, or clarify how indexing works.

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 each parameter having a description. The description adds minimal extra meaning (e.g., 'recent observations' and field list), but does not elaborate beyond the schema defaults and optionality.

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 returns a 'compact index of recent observations' with specific fields (ID, type, title, importance, age, citation URI). While the verb is implied, it distinguishes itself from sibling memory tools by focusing on 'index' rather than delete, get, save, or 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 versus alternatives like memory_search or memory_get. There is no mention of prerequisites, context, or when not to use it.

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