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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is known to be a safe read operation. The description adds minimal behavioral context beyond the word 'copyable', which suggests copying but without details.

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

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

At only four words, the description is under-specified and lacks clarity. Conciseness should not trade off against meaningful content.

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 low schema coverage, absence of output schema, and complex sibling context, the description is entirely inadequate. The agent would have no clear understanding of the tool's purpose or 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 input schema has one required parameter (artifactId) with 0% description coverage, and the description does not explain what artifactId means or how to use it. It adds no semantic value.

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 'Self-contained copyable artifact content' is vague and does not clearly state the tool's action. It fails to distinguish from siblings like artifact.get or artifact.get_chunk.

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 artifact.get or artifact.get_chunk. The description lacks contextual direction.

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 indicate destructiveHint=true. The description adds that files are also deleted, but lacks details on irreversibility, permissions, or side effects. With annotations present, this is adequate but minimal.

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 wasted words. Could be slightly expanded but remains concise and front-loaded with the 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?

For a simple destructive operation with one parameter and no output schema, the description is complete enough for basic use but lacks details on error states or return value.

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 0%. The description does not mention the artifactId parameter, relying solely on its name for meaning. This is insufficient for a parameter with no schema 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 verb 'Delete' and the resource 'artifact and its files'. It distinguishes from siblings like artifact.put, artifact.get, and artifact.gc.

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 artifact.gc. No prerequisites or context provided beyond the destructive nature implied by annotations.

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 already indicate destructive nature (destructiveHint=true). Description adds that it removes only expired unpinned artifacts, but does not detail other behaviors such as batch processing, error handling, or 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?

Single short sentence with no wasted words. Efficiently communicates the core 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?

Description is sufficient for a simple tool with no parameters, but lacks details on what 'expired' means (e.g., time-based) and when to invoke compared to artifact.delete. Could be more complete with usage guidelines.

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?

No parameters in the schema, so description need not add param info. Baseline 4 applies for 0 params.

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 it removes expired unpinned artifacts, specifying the action (remove) and the resource (expired unpinned artifacts). This distinguishes it from artifact.delete (removes specific artifacts) and artifact.pin (pins artifacts).

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 or not use this tool versus alternatives like artifact.delete. The description implies it's for cleanup of expired artifacts but does not provide context on prerequisites 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?

Annotations already indicate read-only and non-destructive behavior. Description adds 'Returns content as text', providing the return type. However, no mention of error handling, size limits, or encoding, which would be valuable for a read 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, no wasted words. The first sentence states the purpose, the second adds the return type. Efficiently 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 get-by-ID tool with one parameter and no output schema, the description is adequate. It covers the core functionality and return format. However, it lacks mention of potential truncation or error states, which would be helpful for complete context.

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

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

The only parameter (artifactId) is described as 'by ID', but the description does not clarify the format or source of the ID. With 0% schema coverage, the description should compensate but fails to add meaningful guidance 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?

Description clearly states the action ('Retrieve'), the resource ('artifact by ID'), and the output ('Returns content as text'). It effectively distinguishes from sibling tools like artifact.put, artifact.delete, and artifact.get_chunk.

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., artifact.get_chunk for large content, artifact.list for multi-item retrieval). No prerequisites or context for using the tool.

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 already declare readOnlyHint=true and destructiveHint=false, so the description adds no further behavioral details (e.g., out-of-bounds handling, chunk size).

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 but at the expense of essential information; it could be expanded without becoming overly 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 two parameters with no schema descriptions and no output schema, the description is too brief to be complete, lacking details on chunk behavior and related tools.

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 0%, yet the description does not explain the chunkIndex parameter or its default value, leaving the agent without meaningful parameter 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 clearly states it reads one chunk of a large artifact, but does not differentiate from the sibling artifact.get tool, which likely reads the entire artifact.

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 artifact.get or when chunking is appropriate.

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 already declare readOnlyHint=true and destructiveHint=false, so the agent knows it is safe. The description adds 'with metadata' but does not disclose behavioral traits like pagination, authentication needs, or result limits. With annotations covering safety, the description adds minimal value.

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, concise and front-loaded. However, it sacrifices necessary detail for brevity. It could include a few more sentences to cover parameters 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 three undocumented parameters, no output schema, and no param descriptions, the description fails to provide a complete picture. It does not explain filtering, pagination, or what metadata is returned, making it inadequate 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?

Schema description coverage is 0%, yet the description does not explain any of the three parameters (tag, limit, pinned). The agent has no clue how these parameters affect the listing, making it insufficient for correct invocation.

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 'artifacts with metadata', indicating a collection retrieval. It differentiates from sibling tools like artifact.get (single artifact) but could be more explicit about scope (e.g., 'all artifacts in the current 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 is provided on when to use this tool versus alternatives like artifact.get or symbol.source. The description lacks context about prerequisites, typical use cases, 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?

The description adds behavioral context beyond annotations: it states that pinned artifacts survive garbage collection. Annotations already indicate the tool is not read-only and not destructive, and the description does not contradict them.

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 short (two words plus parenthetical), which is concise and front-loaded. However, it could be slightly expanded to improve clarity 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?

Given no output schema and low complexity (2 params), the description provides minimal but sufficient info. It lacks guidance on when to use, but covers the core functionality. It is adequate but leaves 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?

With 0% schema description coverage, the description does not explain the meaning of the parameters beyond their names. It mentions 'Pin/unpin' implying a toggle, but lacks specifics on artifactId or the default value of pin.

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 'Pin/unpin' artifacts, with the parenthetical 'pinned survive GC' explaining the effect. It uses a specific verb and resource, and distinguishes from sibling tools like artifact.delete or artifact.gc.

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 given on when to pin vs unpin, or how this tool relates to alternatives like artifact.gc. The description does not provide context for appropriate 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?

Annotations declare mutating (readOnlyHint=false) but not destructive. Description adds content-addressing behavior (idempotent, dedup) and mentions compression and TTL. However, it omits side effects like size limits, overwrite behavior, or auth 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?

The description is a single sentence with no fluff, but it lacks structure and omits critical details. While efficient, the conciseness comes at the cost of completeness.

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 8 parameters, no output schema, and moderate sibling tools, the description is severely underspecified. It does not explain how to use parameters, constraints, or return values, leaving the agent with significant 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 description coverage is only 25% (2 of 8 parameters have descriptions). The tool description does not explain any parameters beyond the schema, failing to compensate for low coverage. Parameters like pin, compress, redacted, sensitive are left undocumented.

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 (store), resource (artifact), and key characteristics (content-addressed, SHA-256, compression, TTL, returns artifact ID). It effectively distinguishes from sibling tools like artifact.get (read) and artifact.delete.

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 file.contracts or artifact.put variants. Usage is implied (storing an artifact) but no explicit context, prerequisites, 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?

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds the specific metrics (count, size, compression) but lacks details like scope (global vs per-workspace) or return format. Does not contradict 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?

The description is extremely concise, using just a few words to convey the core purpose. No unnecessary text.

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 and no parameters, the description is minimal. It provides the basic type of information but lacks details on data scope, real-time nature, or examples. Adequate but not 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?

No parameters exist, so schema coverage is 100%. Description adds no parameter info, but with zero parameters the baseline is 4.

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

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

The description clearly states the tool returns storage statistics including count, size, and compression. It distinguishes from sibling tools like artifact.list which lists individual artifacts.

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 information on when to use this tool versus alternatives, such as artifact.list for individual artifact details. Missing any 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?

Annotations indicate readOnlyHint=false (write operation) and destructiveHint=false. Description adds that it builds a packet with ranking and quality check, but does not disclose other behavioral aspects like auth needs or rate limits. No contradiction with 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?

Extremely concise (one sentence) and front-loaded with purpose, but fails to provide necessary parameter context, making it under-specified rather than efficiently concise.

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

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

Given 7 parameters with no schema coverage, nested objects, and no output schema, the one-line description is completely inadequate. It does not explain what L0-L3 packet means, how ranking works, or quality check requirements.

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 0%, and the description does not explain any of the 7 parameters (3 required). Agents have no guidance on how to use 'mode', 'task', 'evidence', etc.

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 uses specific verb 'Build' and resource 'L0-L3 packet', with features 'ranking + quality check' and scope 'Repository-scoped'. This clearly distinguishes from sibling tools like context.expand and context.inspect.

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. Description only states scope, no when-not or alternative references.

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 present (readOnlyHint=false) but description adds no behavioral detail beyond 'loads symbols'—still unclear if mutation occurs. No mention of side effects, permissions, or rate limits.

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 short but at the expense of clarity. A single vague phrase is not appropriately sized; it sacrifices informativeness for brevity.

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

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

With no output schema, no parameter explanations, and a one-line cryptic description, the tool is essentially undefined for an AI agent. Lacks all necessary 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?

Schema coverage is 0%: description doesn't explain any parameter. The two parameters (contextId, requests with nested fields) are left completely ambiguous. Baseline requires compensation, but none provided.

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

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

The description 'FIXED: path validated, loads symbols into packet' is a cryptic developer note. It does not state what the tool does in clear terms; verbs are vague and 'packet' is undefined. Fails to distinguish from sibling tools like context.create or symbol.context.

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 gives no context about prerequisites, 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?

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds no behavioral context beyond this; it is cryptic and potentially confusing. No contradiction is present.

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 short, but it sacrifices clarity for brevity. It is under-specified rather than concise, wasting the opportunity to convey useful 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?

Given the cryptic description, no output schema, and no parameter guidance, the tool definition is completely inadequate. An agent would struggle to select and invoke this 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 one parameter 'contextId' with 0% description coverage. The description does not explain what 'contextId' refers to or how to use it, providing no added meaning.

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

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

The description 'Loss manifest + quality.' is vague and does not clearly state what the tool does. It lacks a verb and a specific resource, making it unclear whether it inspects, retrieves, or modifies something. Sibling tools like 'context.create' and 'context.expand' have clearer purposes.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention any conditions, prerequisites, or exclusions, leaving the agent without direction.

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 already declare readOnlyHint=true and destructiveHint=false, indicating safe read-only behavior. The description adds 'includes full body ranges', which hints at output structure but does not clarify scope or side effects. It adds minimal value beyond 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?

The description is short (two sentences) but lacks structure and clarity. It is concise but not necessarily effective, as it sacrifices informativeness for brevity.

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

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

With no output schema and minimal parameter description, the agent lacks sufficient detail to understand what the tool returns or how to interpret results. The description is incomplete for effective use.

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

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

Schema coverage is 0%, and the description does not explain the parameters (repository_id, filePath). The name 'filePath' is self-explanatory, but repository_id is not described. The agent gains no extra understanding 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 is vague: 'Layer 1: contracts for all symbols' does not clearly state the tool's action or what 'contracts' entails. The term 'FIXED' and 'includes full body ranges' add ambiguity rather than clarity. The purpose is not discernible without additional context.

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 sibling tools like symbol.source or symbol.context. The description does not mention any selection 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?

Annotations already indicate destructiveHint: true and readOnlyHint: false. The description adds no behavioral context beyond that, and is entirely uninformative.

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?

Although short, the description is not concise in a useful way. It is an irrelevant note rather than a proper functional description.

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 required param, the description should explain what applying a patch entails, effects, and prerequisites. It is completely missing all 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?

With 0% schema description coverage and the description not mentioning the single parameter 'patchId', the agent gets no help understanding what value to provide.

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 is a changelog note ('FIXED: real hash re-check works now') that fails to state what the tool does. The title 'Apply Patch' gives a vague hint, but the description itself is meaningless for an agent.

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 patch.propose, patch.validate, or patchset.apply. The description provides no 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 does not disclose any behavioral traits. It mentions a fix but not the tool's action (creating a patch). Annotations exist but are insufficiently supplemented. No contradiction with 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?

The description is very short but fails to communicate tool purpose. It is under-specified rather than concise; every sentence should add value, but this one does not.

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, no parameter descriptions, and a non-descriptive annotation, the description is completely inadequate for a tool with two required parameters and related siblings.

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 two required parameters (edits, contextId) with no descriptions. The description adds no information about their meaning or purpose, and schema coverage is 0%.

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 'FIXED: patchId linked to validate/apply via randomUUID' is a changelog note, not a statement of tool purpose. It does not specify what the tool does, such as proposing a patch, which is implied by its name and siblings.

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

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

No usage guidance is provided. The description offers no context on when to use this tool versus siblings like patch.validate, patch.apply, or patchset.propose.

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 already indicate destructiveHint=true. The description adds value by specifying atomicity and rollback journal, providing behavioral context beyond the annotation.

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 fluff. Front-loaded with the key action and distinctive features (atomically, rollback journal).

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 prerequisites (e.g., patchset must be validated), workflow context, and details about rollback journal. Given no output schema, more context is needed for an agent to understand side effects.

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

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

The single parameter patchsetId has no schema description (0% coverage). The description does not explain its purpose or how to obtain it, relying solely on the parameter 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 applies validated files atomically with a rollback journal. The verb 'apply' and resource 'validated files' are specific. However, it does not explicitly distinguish from siblings like patchset.propose or patchset.validate beyond the 'validated' qualifier.

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. The mention of 'validated files' implies prior validation, but there is no statement of prerequisites, exclusions, or alternative tools like patch.apply.

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 already indicate this is not read-only and not destructive. The description adds 'atomic' and 'expected hashes' but does not explain error behavior, reversibility, or interaction with other tools. Minimal added value.

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 clear structure. Could include more context without becoming verbose, but it is efficiently worded.

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 provided, and the description omits return value, error conditions, or usage examples. For a tool with required nested parameters and important semantics (atomic, hashes), 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?

Schema description coverage is 0%, meaning the description does not explain any of the two parameters. The fields 'expected_hash' and 'new_content' in the 'changes' array are left ambiguous. The description adds no semantic value 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 identifies the action (propose), resource (multi-file patch set), and key attributes (atomic, expected hashes). However, it does not explicitly differentiate from the sibling 'patch.propose', though the name implies multi-file vs single-file.

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

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

No guidance on when to use this tool versus alternatives like 'patch.propose' or 'patchset.validate'. No description of prerequisites 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?

Annotations already declare destructiveHint: true, so the description's mention of 'backup journal' adds some context about the mechanism. However, it does not discuss reversibility, permissions, or side effects beyond restoration.

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 of 8 words, no fluff, front-loaded with the action. Every word is necessary.

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 destructive tool with no output schema and minimal annotations, the description lacks crucial context: what a backup journal is, prerequisites, error states, or whether the operation is reversible. Incomplete for safe 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?

Schema has 0% description coverage, and the tool description does not mention the required parameter patchsetId or its meaning. The agent receives no guidance on what value to provide.

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 verb 'Restore' matching the title's 'Rollback', and specifies the resource as 'every file from the patch-set backup journal.' It clearly distinguishes from sibling tools like patchset.apply by indicating a reversal operation.

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 given on when to use or not use this tool versus alternatives like patchset.apply or patchset.validate. The description only states what it does, not the context of use.

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

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

The description does not disclose behavioral traits beyond the annotations. It says 'Validate' but does not clarify if it modifies state, returns results, or has side effects. Given readOnlyHint=false and destructiveHint=false, additional context about whether validation is a safe read operation would help.

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 it is too minimal. It could include more information without being 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 simplicity of the tool (1 param, no output schema), the description fails to provide enough context for an agent to use it effectively. Missing details include what validation entails, return format, and how to get the patchsetId.

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 single parameter 'patchsetId' is a string with no description in the schema (0% coverage). The description does not explain what a patchsetId is, how to obtain it, or its format. The title implies it's a patch set identifier, but that is insufficient.

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 'Validate' and the resource 'the whole patch set in one sandbox'. It distinguishes this tool from siblings like patch.validate (singular patch) and other patchset actions (propose, apply, rollback).

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 like patch.validate. It does not mention prerequisites, 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?

Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds 'All state from server' hinting at server-side checks. However, it does not detail what validation does (e.g., conflict detection, side effects) beyond the annotation 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?

Two sentences, zero waste. The purpose is front-loaded, and every word adds necessary 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?

Despite low complexity (1 param, no output schema), the description omits what validation returns (pass/fail, details). Without output schema, the agent lacks clues about what the tool outputs, reducing 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?

With 0% schema coverage, the description adds value by explaining the source of patchId ('from patch.propose'), which helps the agent understand parameter origin. More detail on format or constraints would push higher.

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

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

The description states a specific action 'Validate proposed patch' with a clear verb and resource. Among siblings like patch.propose and patch.apply, it is distinct as a validation step.

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 specifies a prerequisite ('Requires patchId from patch.propose'), providing sequential context. However, it does not explicitly exclude alternatives or state when not to use.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds that it returns 'symbols changed since last scan/watch', which provides context about the data scope but omits details like pagination, ordering, or behavior when no changes exist.

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?

Description is a single, short sentence that directly states the purpose. While concise, it could benefit from a second sentence for parameter clarification without losing brevity.

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

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

Given two parameters, no output schema, and multiple sibling tools, the description is incomplete. It does not explain the limit parameter's effect, the return format, or how to handle cases where no scan/watch has occurred.

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 0%, so the description must explain parameters. However, it does not mention limit or repository_id, leaving their purposes unclear. No additional meaning beyond the schema's type and default is provided.

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

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

Description states 'Symbols changed since last scan/watch for a repository' which clearly conveys the tool's function and resource. It distinguishes from sibling tools like project.scan or project.watch_start by focusing on retrieving changes rather than initiating scans or watches.

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. The description implies usage after a scan or watch, but does not specify prerequisites or mention when to use other tools like symbol.source or project.snapshot.

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 already declare readOnlyHint=true and destructiveHint=false, so the description's mention of 'file tree + exports' aligns with a read operation. It adds context about output type but does not disclose additional behavioral traits beyond 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?

The description is a single concise sentence with no extraneous words, front-loading the key 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?

While the tool is simple, the description lacks details about the path format, nesting of file tree, or how exports are represented. Combined with no output schema and missing parameter explanations, it is incomplete for an agent to fully understand 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?

With schema description coverage at 0%, the description adds no meaning to the parameters (path, repository_id). It fails to explain their purpose or format, leaving the agent with only the type information from 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 'Layer 0: file tree + exports for a repository' clearly states the tool outputs the file tree and exports, using a specific verb and resource. It distinguishes from siblings like project.scan and file.contracts.

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 like project.scan or file.contracts. The description only says 'Layer 0', implying it's basic but not stating 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?

Annotations indicate non-read-only and non-destructive, but description adds minimal behavioral context beyond purpose. Doesn't mention side effects, idempotency, or cost. With annotations present, 3 is appropriate.

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

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

Two concise sentences with no filler. Front-loaded with purpose and critical prerequisite.

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?

Description lacks parameter explanations, return value details, and behavioral nuance. For a tool generating a call graph, more context about output or side effects is needed.

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

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

Schema has 3 parameters with 0% description coverage and no parameter details in description. The description does not explain path, exclude, or repository_id, forcing reliance on parameter names alone.

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 specific action: 'Build cross-file call graph' and identifies prerequisite relationship with symbol.context. Distinct from siblings like project.map or symbol.source.

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

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

Explicitly states prerequisite: 'Required before symbol.context.' This gives clear usage context, though no when-not or alternatives 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?

Annotations indicate non-read-only and non-destructive, but the description adds no extra behavioral context (e.g., effect on repository, 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?

Single sentence is concise but lacks structure or additional 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 no output schema, the description should at least clarify return value or side effects; it fails to provide that 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?

With 0% schema description coverage, the two parameters (path, repository_id) are completely undescribed in the tool definition, leaving the agent guessing their meaning and format.

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 'Take a snapshot for a repository' clearly states the verb and resource, distinguishing it from siblings like project.scan or project.map, but it could be more specific about what a snapshot entails.

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, nor any mention of prerequisites or common usage patterns.

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?

Minimal disclosure: annotations provide non-destructive, non-read-only info but the description does not add behavioral traits like background execution, resource impact, or the need to eventually call project.watch_stop.

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

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

Very concise (8 words) but too brief for the tool's complexity. Front-loaded purpose, but omitted critical 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?

Incomplete for a tool with 4 parameters, no output schema, and related siblings. Lacks information on return value, watcher lifecycle, and parameter constraints.

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 50% and the description adds no parameter details. Undocumented parameters (path, exclude) remain unexplained; the description could clarify their meaning or 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 the verb 'Start' and the resource 'incremental file watcher' scoped to a specific repository. However, it does not differentiate from sibling tools like project.scan or project.watch_stop, which 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?

No guidance on when to use this tool versus alternatives (e.g., one-time scan with project.scan) or prerequisites (e.g., repository existence). The agent is left to infer 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?

Annotations already indicate readOnlyHint=true (safe, no side effects), but the description adds no further behavioral context—e.g., what the watcher state consists of (boolean, list?), or how to interpret the response. The description is merely a restatement of the title.

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 brief (4 words) but under-specified, not concise. Concision without completeness is not helpful. The description should be expanded to include essential details.

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

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

No output schema and no description of what the tool returns. For a status tool, the return value is critical. Also lacks parameter explanations, making the tool poorly documented overall.

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 sole parameter repository_id has no description in the input schema (0% coverage) and the tool description does not explain it. With one required parameter, failing to describe its meaning is a serious omission.

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 'Current watcher state for a repository' is a noun phrase that implies the tool returns state, but lacks a verb like 'Get' or 'Retrieve'. While it distinguishes from sibling actions (watch_start, watch_stop), it's vague about what the state includes.

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

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

No guidance on when to use this tool versus alternatives like watch_start or watch_stop. The agent must infer its purpose from the name and description.

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

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

Annotations indicate non-read (false) and non-destructive (false). Description adds 'Stop' but does not elaborate on side effects, state changes, or whether stopping is reversible. Minimal behavioral disclosure.

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

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

Single sentence with no wasted words. Direct and to the point, though slightly under-informative.

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

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

Given the tool's simplicity (one param, no output schema), the description is too minimal. It does not explain when to stop a watcher or what happens after stopping, leaving 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?

Schema has one parameter (repository_id) with zero description coverage. The description does not add any meaning beyond the schema, failing to compensate for the lack of parameter details.

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 ('Stop') and the resource ('watcher for a specific repository'). It distinguishes from sibling tools like project.watch_start and project.watch_status.

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., watch_start, watch_status). Does not mention prerequisites or context for stopping a watcher.

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 already declare readOnlyHint=true and destructiveHint=false, so the tool is known to be read-only. The description adds the 'REPO-ISOLATED' behavior, but does not disclose other traits like response format, error handling, or rate limits. It adds minimal value beyond 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?

The description is extremely concise at one sentence. It is front-loaded with the primary purpose. However, it is perhaps too sparse, missing opportunities to add structure or list parameters.

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

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

With no output schema and a brief description, the tool lacks crucial context. There is no information about return values, pagination, error cases, or usage examples. For a tool with 4 parameters and no schema descriptions, the description is incomplete.

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

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

Schema description coverage is 0%, meaning the schema has no parameter descriptions. The description partially compensates by listing 'Callers/callees/tests' which maps to the 'what' parameter enum values. However, it provides no explanation of the other parameters (symbol, filePath, repository_id), leaving them undefined.

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 'Callers/callees/tests for a repository.' This is a specific verb+resource combination. However, it does not explicitly differentiate from sibling tools like 'context.expand' or 'symbol.source', though the 'REPO-ISOLATED' hint provides some distinction.

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

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

There is no guidance on when to use this tool versus alternatives like 'context.expand' or 'symbol.source'. The phrase 'REPO-ISOLATED' implies a scope constraint, but no explicit when-not or alternative tool references 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?

Annotations already indicate readOnly and non-destructive. The description adds 'EXACT' but lacks details on behavior like whether the source is fetched from cache or live, size limits, or formatting. It also inconsistently mentions 'source and contract' while the view parameter includes 'reference' as a third option, which could confuse agents.

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 phrase), which is efficient but sacrifices clarity. It lacks structure such as separating purpose from behavior and usage. While no words are wasted, the brevity results in omission of critical information needed for correct tool invocation.

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, and there are many sibling tools, the description is insufficient to guide an agent on correct usage. It does not explain return format, error conditions, or relationship to similar tools like file.contracts. An agent would lack context on when and how to use the view parameter.

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 75% schema coverage, the schema itself describes parameters symbol, filePath, repository_id. The description adds no additional meaning for parameters; it doesn't explain the view parameter's options or what 'contract' versus 'source' versus 'reference' means in this context. The 'EXACT source' phrase is ambiguous regarding parameter usage.

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

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

The description clearly identifies the tool returns the exact full symbol source and contract scoped to a repository. 'EXACT' emphasizes precision, and 'repository-scoped' sets scope. However, it doesn't explicitly state the action verb (get/retrieve), but the context implies reading. Differentiates from siblings like symbol.context (context vs full source).

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 indicate when to choose this tool over alternatives like symbol.context or file.contracts. No scenario or prerequisite information is given.

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