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

With no annotations, the description bears the full burden of disclosing behavior. It only reveals that main specs will be updated, but does not explain what archiving entails (e.g., whether it's reversible, if it moves/copies data, or requires permissions). This is insufficient for a mutation 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, concise sentence that front-loads the key action and effect. It contains no wasted words and is 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?

For a mutation tool with no annotations and no output schema, the description lacks critical behavioral context and usage guidance. It does not address side effects, prerequisites, or the meaning of 'archived', making it incomplete for an agent to safely invoke.

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?

Both parameters (changeName and skipSpecs) are described in the schema with 100% coverage, so the description adds no additional meaning. Baseline score of 3 is appropriate when the schema already documents all 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 primary action (archive a change) and the secondary effect (update main specs). It uses a specific verb and resource, and the 'archive' action is distinct from sibling tools like openspec_update or openspec_new_change, though it doesn't explicitly call out an alternative.

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 openspec_update or openspec_list. The only contextual clue is 'completed change', which implies a prerequisite but does not explain when archiving is appropriate or when to choose a different 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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It fails to mention that initialization may alter the project (e.g., creating files, cleaning legacy files via the 'force' parameter), require confirmations, or have side effects. The only behavioral hint comes implicitly from the schema's 'force' parameter, which is not referenced in the description.

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 redundant words. It is front-loaded and readable, but the brevity borders on underspecification, so it earns 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?

For a tool that initializes a project, the description is far too thin. It does not explain what is created, whether it is interactive, how the 'tools' parameter affects behavior, or what the expected result is. With no output schema and no annotations, the description leaves substantial 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 description coverage is 100% with clear descriptions for both 'force' and 'tools', including values and defaults. The description itself adds no additional parameter context, but the schema sufficiently documents the parameters; baseline 3 is appropriate.

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

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

The description states the specific action ('Initialize OpenSpec') and the target context ('in your project'), which clearly conveys the tool's purpose. It distinguishes itself from siblings like openspec_update and openspec_list by indicating setup rather than ongoing operations, though it lacks specific details about what initialization 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 is provided on when to use this tool vs alternatives. There is no mention of prerequisites, first-time setup context, or exclusions (e.g., 'use openspec_update for existing projects'), leaving the agent to infer usage solely from the name 'init'.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool 'outputs' instructions, implying a read-only operation, but does not disclose whether it has side effects, requires specific permissions, or how the output is structured. This is insufficient for a tool with no annotation support.

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 primary action and target. It avoids verbosity and directly states the purpose, though it could benefit from slightly more detail without becoming bloated.

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 (3 params, no output schema), the description is still too terse. It lacks context about what 'enriched instructions' means, what 'apply' refers to, and any expected output format or behavior. This is comparable to the 'update_drive' example, which scored 2 for 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 schema descriptions cover 100% of parameters, so the baseline is 3. The tool description 'for an artifact or apply' aligns with the 'artifact' parameter but doesn't add new meaning beyond the schema. The 'json' and 'changeName' parameters are only explained in the schema, which is adequate.

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 outputs enriched instructions for an artifact or 'apply'. This action is specific and distinct from sibling tools like openspec_show or openspec_read_file, which likely display or read content. However, the term 'enriched' is somewhat vague, leaving ambiguity about what kind of enrichment is provided.

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 doesn't mention any prerequisites, exclusions, or specific scenarios. The only hint is the name and phrase 'for an artifact or apply', which implies usage but lacks explicit 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?

With no annotations, the description must carry the burden. It mentions the JSON return behavior, but does not fully disclose whether it's read-only, what the default output format is, or any side effects. The behavioral information is 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?

The description is concise, front-loaded, and every sentence adds information about the tool's function and output. 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 sibling tools, the description lacks guidance on how this tool fits in the workflow. It doesn't clarify the difference between listing and showing, or mention any prerequisites or side effects. The tool is simple, but the context is incomplete.

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

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

Schema coverage is 100%, so the description adds minimal extra meaning. It implies the default is changes unless specs=true and mentions JSON array output, providing slight value beyond the schema's 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 lists items (changes or specs), identifying a specific verb and resource. It doesn't explicitly distinguish from sibling tools like openspec_show, but the 'list' verb is distinct enough to convey the basic 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?

No guidance is provided on when to use this tool versus alternatives like openspec_show or openspec_status. The description only states what it does, not when to choose it 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 the full burden of disclosing behavioral traits. It only mentions the action of creating a change directory but does not explain side effects, what files are generated, or any side effects. This is minimal and insufficient for a mutation-style 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, focused sentence without any fluff, which is efficient. However, it is arguably too terse to be fully informative, so it earns a 4 rather than 5.

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

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

Given the tool has two parameters, no output schema, and no annotations, the description is notably incomplete. It does not explain what a 'change directory' is, what gets created, or anything about the surrounding workflow, which would be necessary for an agent to use it correctly in 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 input schema covers both parameters (name and description) with descriptions, and schema_description_coverage is 100%. The tool description adds no additional parameter semantics, but per rubric, with high coverage this is acceptable. However, it does not compensate for any nuance 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 'Create a new change directory' clearly states the verb (create) and resource (change directory), making it easy to understand the tool's function. However, it does not explicitly differentiate this from sibling tools like openspec_init, which might also involve creation, so it falls short of a perfect 5.

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

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

The description provides no guidance on when to use this tool versus alternatives (e.g., openspec_init or openspec_update). There are no exclusions, prerequisites, or contextual cues, leaving the agent without direction on 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?

No annotations are provided, so the description carries the transparency burden. It conveys a non-mutating, direct read operation and a performance trait ('much faster than show'), but it does not disclose return formatting, error behavior, or whether content is returned verbatim.

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 core action, and every word earns its place. It efficiently conveys purpose and usage guidance without 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?

The tool is a simple file-read operation with a fully documented schema; the description plus schema provide enough context for invocation. It does not mention the output/return value, but for a read-file tool that is largely implied.

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

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

Schema description coverage is 100%, with all three parameters described in the input schema. The description adds no additional parameter context, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Read any OpenSpec artifact directly.' It also distinguishes from the sibling tool `show` by noting it is 'much faster' and for file contents, making the purpose unmistakable.

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

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

It explicitly says 'use this when you need file contents' and contrasts with `show` by speed, giving clear context for selection. It does not fully explain when `show` would be preferred, but the directional guidance is sufficient.

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

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

With no annotations, the description carries the burden of disclosing behavior. It clarifies the target ('cached directory listing') and the action ('force refresh'), but does not mention potential side effects, safety profile, or whether it returns data. Since this is a simple cache refresh, the lack of deeper detail is acceptable but not fully transparent.

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. The first sentence states the action; the second gives usage guidance. 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?

For a zero-parameter tool with no output schema, the description gives purpose and usage, which is sufficient for an agent to decide when to invoke it. It could mention possible return values, but that is not critical for such a simple action. Overall, the description is complete enough given the tool's simplicity.

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

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

The tool has zero parameters, so the schema already fully covers parameter semantics (vacuously). The description adds no parameter info, which matches the baseline of 4 for tools with no 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 uses a specific verb ('Force refresh') with a clear resource ('cached directory listing'), which exactly matches the tool name and distinguishes it from siblings like openspec_list (which lists without forcing a cache refresh).

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

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

Provides explicit when-to-use context: 'Use if you suspect changes were made outside OpenSpec tools.' This clearly indicates the appropriate situation, though it does not name alternatives or exclusions explicitly.

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 behavioral disclosure. It only mentions ambiguous type resolution but doesn't describe output format, side effects, or prerequisites, leaving the agent with limited behavioral context.

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

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

The description is a single, front-loaded sentence that wastes no words. It is appropriately concise for a simple show command.

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 full schema coverage, the description is minimally adequate but lacks usage guidance relative to siblings and doesn't mention the output behavior. It could be improved with a note about when to use it instead of list or read_file.

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 100% of parameters with descriptions. The description adds a small clarification about when to use the type parameter, but otherwise relies on the schema.

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

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

The description clearly states it 'shows a change or spec' with a specific verb and resource. It differentiates from siblings like list or read_file through the 'show' action, though it doesn't explicitly name alternatives.

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

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

It provides no guidance on when to choose show over sibling tools like list or read_file. The only usage hint is 'Use type to specify if it is ambiguous,' which is parameter-specific rather than tool-selection guidance.

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

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

With no annotations, the description must fully disclose behavioral traits, but it only says 'Display,' which is a mild implication of a read-only operation. It does not explain what happens for missing changes, the output format beyond 'status,' or any 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 a single short sentence that front-loads the core purpose without any filler or repetition. It is appropriately concise for the tool's simplicity.

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 explain what 'status' includes, but it does not. It leaves unanswered questions about the format of the status output, failure handling, and how the json flag affects the result, making it minimally complete for a simple 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?

The schema describes both parameters (changeName and json) with 100% coverage, so the baseline is 3. The description adds little beyond the schema, merely restating that a change is involved and not enriching the json parameter's semantics.

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 ('Display') and names the resource ('artifact completion status for a change'), clearly stating the tool's function. It does not explicitly distinguish itself from sibling tools like openspec_show, but the intent is unambiguous.

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 openspec_show or openspec_list. The description only implies status-checking for a specific change and does not state exclusions, prerequisites, or 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 responsibility for disclosing behavioral traits. It only says 'Update' without explaining whether this modifies files in place, requires existing files, is destructive, or has side effects. There is no mention of permissions, error conditions, or what happens to the files being updated.

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

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

The description is a single, concise sentence with no wasted words. It is front-loaded with the action and target. While it is terse, it meets the standard for conciseness, earning a top score for structure.

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 parameters, no output schema, and no annotations, so the description is the only source of information. It fails to explain what 'update' means, the context of instruction files, or how this tool fits into the OpenSpec workflow. Given the sibling tools like openspec_instructions and openspec_refresh_cache, there is ambiguity about the tool's exact role. The description is far from complete.

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

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

The input schema has zero parameters, so the description does not need to explain parameter details. Per the rubric, 0 parameters gives a baseline of 4. The description adds nothing about parameter semantics because there are none, but it is not misleading. It would be better if it explained how the update is triggered without parameters, but that is beyond this dimension.

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 ('Update') and resource ('OpenSpec instruction files'), which clearly states the action and target. It differentiates from sibling tools like openspec_list, openspec_show, and openspec_validate because 'update' implies a write operation. However, it does not elaborate on what 'instruction files' are or the scope of the update, so it stops short of a 5.

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 information about when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or related tools such as openspec_instructions or openspec_new_change. The agent is left without guidance on choosing this tool among the many siblings.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'validate' but does not explain whether validation is read-only, what side effects might occur, how errors are reported, or whether it modifies anything. This lack of transparency is significant for a tool that could potentially alter state.

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 unnecessary words. However, it may be overly terse, sacrificing valuable context for brevity. Still, it earns its place and is not padded.

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 four optional parameters and no output schema, so the description should explain the validation workflow and expected outcomes. It does not mention how the flags (all, json, strict, itemName) affect behavior, what a validation report looks like, or how this interacts with other openspec commands. This makes it incomplete for an agent to use 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 provides 100% coverage for all four parameters, each with a description, so the baseline is 3. The textual description adds no additional meaning beyond the schema, but since schema coverage is complete, it does not need to 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 identifies the action ('validate') and the resource ('a change proposal or spec'), which differentiates it from sibling tools like openspec_list or openspec_show. It is concise and uses a specific verb, but it doesn't elaborate on the scope or variants of validation.

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

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

The description gives no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. It simply states the function, leaving the context and selection logic entirely to the agent.

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