mk-spec-master

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

With no annotations, the description carries full burden. It transparently details the analysis types, return structure, and the fact that sweeping all specs is possible. It lacks mention of performance implications or read-only nature, but is adequate.

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 dense with information but remains coherent and front-loaded. It covers multiple modes, return fields, and severity levels in a single paragraph without excessive wordiness.

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 moderate complexity, the description provides a complete picture: input modes, analysis types, return structure with fields, and linkage to a sibling tool. It answers the key questions an agent would have.

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 fully compensates. It explains the purpose of each parameter: spec_id for one spec, raw_text for a draft, omitting both to sweep all. This adds significant meaning beyond the schema.

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

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

The description clearly states the tool runs heuristic checks on spec bodies, listing specific types of issues detected (vague language, implementation leakage, role references without preconditions). It distinguishes from siblings by explicitly mentioning pairing with propose_spec_improvements.

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 three clear usage modes (by spec_id, raw_text, or sweep all) and refers to a sibling tool for follow-up. However, it does not explicitly state when not to use this tool or compare with other analysis tools.

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

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

With no annotations, the description carries full burden and discloses all essential behaviors: scanning files, owner detection within 30 lines, test_node_id format, calling link_test_to_spec, and dry_run effect. It is transparent about the operation and 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 reasonably concise given the amount of detail, with the main purpose stated upfront. It includes necessary technical specifics without excessive verbosity, though it could be slightly streamlined.

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 lacking annotations and output schema, the description provides rich context: default directories, language support, tag pattern, matching heuristic, test_node_id format, return object fields, and dry_run behavior. It covers all aspects needed for an agent to use the tool correctly.

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

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

The description adds significant meaning beyond the input schema: it explains default behavior for test_dir, enumerates languages concretely, and provides the only description for dry_run. Schema coverage is 67%, but the description compensates fully, making parameter usage clear.

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 scans a directory for @spec tags and calls link_test_to_spec for each found pair, specifying the supported languages and matching logic. It distinguishes itself from the sibling link_test_to_spec by acting as a batch automation tool.

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

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

The description explicitly mentions when to use the tool: when a user says 'rebuild the spec coverage' or 'sync test → spec links after the refactor'. It also advises setting dry_run to preview. However, it does not explicitly state when not to use it or mention alternatives.

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

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

No annotations are provided, so the description must carry the full burden. It discloses that scenarios are classified via keyword heuristics and split into Given/When/Then where possible, and it details the output fields. However, it does not cover side effects, error behavior, or prerequisites beyond the input format. This partial disclosure is adequate but not comprehensive.

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

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

The description is concise and well-structured: it opens with the purpose, then explains the method, output format, and a pairing suggestion. Every sentence adds value without redundancy or excessive length.

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

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

Given the tool's moderate complexity and lack of output schema, the description provides a complete picture of inputs, outputs, and workflow position. It defines the scenario fields and suggests a next step. Minor missing details (e.g., handling of unscoped input) are acceptable for a processing 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 input schema has 0% description coverage, so the description compensates by explaining that the parameter is the acceptance_criteria array from parse_spec. It does not detail the array's structure beyond mentioning required text field, but it provides contextual linkage to another tool. This adds moderate 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 clearly states the tool converts parsed acceptance criteria into testable scenarios, specifying the input source (from parse_spec) and output structure (Given/When/Then with classification). This distinguishes it from siblings like parse_spec (which likely produces the input) and generate_test_plan (which produces a markdown handoff).

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

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

The description explicitly instructs to pass the acceptance_criteria array from parse_spec, providing a clear before/after context. It also suggests pairing with generate_test_plan, reinforcing a workflow. Although it does not list exclusions or alternatives, the guidance is sufficient for correct usage.

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

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

The description explains the expected behavior (read operation with no side effects) and clarifies the ID interpretation per source type. However, it lacks details on error handling, permissions, or potential issues like missing IDs.

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, with each sentence adding important information: purpose, ID clarification, return structure, and a practical pairing suggestion. No unnecessary words.

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

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

Given the simple tool with one parameter and no output schema, the description covers the return fields explicitly. It is complete for a basic fetch, though it omits error handling and edge cases.

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

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

The schema provides no description for spec_id, but the description compensates fully by explaining its meaning in different contexts (markdown_local vs github_issues), adding significant value beyond the raw 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 that the tool pulls a single spec by ID from the active source, specifies the ID format for markdown_local and github_issues, and distinguishes itself from siblings like list_specs by focusing on individual retrieval.

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 some usage guidance by suggesting pairing with parse_spec, but it does not explicitly state when to use this tool versus alternatives like list_specs or search tools, nor does it mention any 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?

No annotations are provided, so the description carries the full burden. It describes the process steps (fetch, parse, extract, emit) and the return structure. However, it does not disclose behavioral traits such as side effects, idempotency, authentication needs, or rate limits. The 'one-shot' label hints at no side effects but lacks explicit safety guarantees.

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 with no wasted words. It front-loads the key action ('One-shot: fetch + parse + extract') then covers usage and return values efficiently. Every sentence contributes valuable 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 low schema coverage and no output schema, the description provides process steps, return fields, and ties to another tool (mk-qa-master). It explains the workflow for an AI agent. However, it omits description of spec_id and does not address error scenarios or constraints, leaving minor 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 must explain parameters. It explains target_runner as 'hint the desired output (pytest / jest / cypress / go / maestro)', adding meaning beyond the schema. However, it does not describe spec_id at all, leaving ambiguity about its format or constraints.

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

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

The description clearly states the tool's purpose: fetching, parsing, and extracting for a spec to emit a markdown test plan. It distinguishes itself from siblings by being a one-shot combined operation, unlike separate tools like fetch_spec, parse_spec, or extract_scenarios.

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

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

The description explains the usage context: it is a one-shot operation for generating a test plan ready for mk-qa-master.generate_test, and the AI client loops over scenarios. It implicitly contrasts with sibling tools but does not explicitly state when not to use it or provide alternatives, though the 'one-shot' keyword and mention of other tools in the workflow provide 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 implies a read-only operation via 'snapshot' and describes the return shape. It does not mention destructive behavior or permissions, but the provided information is sufficient for an agent to understand the tool's safety profile.

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 with the core purpose, then provides usage triggers, parameter details, and return structure in a logical order. Every sentence adds value with no redundancy.

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

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

Given the lack of annotations and output schema, the description provides a complete picture: purpose, usage triggers, parameter semantics, and return structure. An agent has all necessary information to correctly select and invoke this 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?

Despite 0% schema description coverage, the description fully explains both parameter defaults and effects: min_tests (set to 0 to find untested specs, set to 1 to hide them) and include_orphans (default true). This adds significant meaning beyond the plain 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 returns a snapshot of spec-test links, with both structured rows and a markdown table. It specifies the exact user queries it addresses ('what's tested' or 'which specs have no tests'), distinguishing it from sibling tools like get_drift_report or get_spec_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?

The description explicitly tells when to call the tool (when a user asks about testing coverage), but does not mention when not to use it or alternatives. It is clear but lacks explicit 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?

Despite no annotations, the description thoroughly explains the process (fetching live spec, recomputing hash, bucketing) and result meanings. It does not explicitly state read-only nature, but implies no writes.

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?

Every sentence contributes value: mechanism, buckets, use cases, optional parameter, output summary. Well-structured and front-loaded with main action.

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

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

Given no output schema, the description still provides sufficient context: return types (counts, details, markdown). Also explains the 'unknown' bucket and how to resolve it, enabling the agent to handle results.

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

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

Single optional parameter spec_id is explained: it narrows the check to one spec. The description adds useful context beyond the bare schema, which had 0% coverage.

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

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

Description clearly states the tool's purpose: detect drift in specs by comparing stored and live ac_hashes. It details the exact mechanism and output buckets, distinguishing it from sibling tools like 'get_drift_signature'.

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 when to use ('has anything changed', 'what's out of sync') and explains the bucketing logic. Lacks explicit when-not or alternative tools, but context is clear.

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

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

Given that no annotations are provided, the description carries the full burden. It explains the scanning logic, the three flagging categories, and the return structure. It does not explicitly state that the tool is read-only or discuss side effects, but the action 'scan' and the return of a report imply no side effects. The description is transparent enough for safe use.

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, front-loading the purpose and then providing usage guidance, parameter details, and return format in a few sentences. Every sentence adds value, with no wasted words.

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

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

Given the tool's simplicity (2 parameters, no output schema, no nested objects), the description is complete. It covers the purpose, when to use, parameter explanations, and the structure of the return value. No additional information is needed for an agent to correctly select and invoke the tool.

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

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

Schema coverage is 0%, so the description must compensate. It fully explains both parameters: window (number of snapshots to scan, default 5) and threshold (minimum recurrence to flag, default 3). This adds crucial meaning beyond the schema's type and 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?

Clearly states it scans recent snapshot history for chronic problems like unstable, chronic_low_quality, and chronic_unhashed. Provides example queries ('which specs keep causing trouble'). However, it does not explicitly distinguish this from its sibling tools such as get_drift_report or analyze_spec_quality.

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 advises when to use the tool: when a user asks about specs that repeatedly cause trouble or long-running pain. This provides clear context. It does not mention when not to use the tool or suggest alternatives, but the 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 full burden. It discloses the return structure '{specs_total, *_count, *[], markdown}', explains layers and how toggles work, and implies a read-only nature. It does not mention destructive traits or auth needs, which is acceptable for a reporting 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 dense paragraph but front-loads the key purpose. Every sentence adds value, though it could be more scannable with bullet points. It is appropriately sized for the complexity.

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

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

Given the complexity (3 layers, 4 params, no output schema), the description covers the output structure and layer behavior. It does not detail the markdown format, but that is acceptable. The tool is well-placed among siblings that handle individual signals.

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%, but the description fully compensates by explaining each parameter: include_coverage/quality/drift booleans (default true) toggle layers, top_n integer (default 10) caps rows. It adds context beyond the schema types, making parameter usage clear.

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

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

The description clearly states it provides a 'Three-layer coach output' that integrates coverage/quality/drift signals into a prioritized markdown plan, with specific use cases like 'what should we fix next'. This distinguishes it from sibling tools that focus on individual signals (e.g., get_coverage_matrix, get_drift_report).

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 gives usage scenarios: 'when a user asks what should we fix next / show me the weekly plan / review the suite'. It also explains how to toggle layers via booleans. However, it does not mention when not to use or provide alternatives (e.g., for individual signals).

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

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

No annotations provided, so description fully discloses behavior: fallback to built-in defaults if file missing, returns source indicator, and content structure.

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

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

Three sentences covering core function, usage guidance, and parameter details with no wasted words. Well structured and front-loaded.

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

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

Despite no output schema, description explains return shape and fallback. For a simple tool with one optional parameter, all essential information is present.

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

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

Schema covers 100% of parameters. Description adds concrete example (section='actors') and clarifies partial-match and case-insensitivity, going beyond schema.

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

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

States core function clearly ('Read SPEC_PROJECT_ROOT/spec-knowledge.md...'), explains when to use it, and differentiates from sibling tools by focusing on session initialization 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?

Explicitly advises 'Call near the start of a session' and explains rationale. Does not explicitly list when not to use or alternatives, but provides sufficient 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 provides behavioral context: it returns {snapshots_total, snapshots[], trend[], markdown} and degrades gracefully with fewer snapshots. It does not explicitly state read-only or permissions, but the use case implies no 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 three sentences with no wasted words. It front-loads the main output, then usage context, then return format and conditions. Every sentence adds value.

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

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

The description covers the main purpose, conditions, and return structure. It lacks output schema but compensates by listing return fields. Minor gaps: no mention of error handling or specific format of 'trend deltas'.

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 'limit' is explained as controlling the number of snapshots ('last N snapshots'), which adds meaning beyond the schema's default value. Schema coverage is 0%, but the description sufficiently clarifies the parameter's role.

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 last N snapshots and trend deltas for specific metrics (spec count, untested, etc.), and explicitly ties it to user queries about improvement or trends, distinguishing it from sibling tools like get_drift_report or get_optimization_plan.

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

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

The description explicitly says when to use: when a user asks 'are we improving', 'show me the trend', or 'how did we do this month'. It also notes the requirement of at least 2 snapshots for trend and graceful degradation. However, it does not mention when not to use or direct alternatives.

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

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

No annotations are present, so the description carries full burden. It discloses the return structure {active, available, version} and that it depends on SPEC_SOURCE env var. However, it does not mention potential failures, rate limits, or behavior if env var is not set.

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: first states core purpose, second gives usage guidance and return format. No redundant words, front-loaded with critical 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 no parameters and no output schema, the description covers the essential: what is returned, when to call, and a brief note on env var. It could elaborate on 'adapters' but is sufficient for a simple informational tool.

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

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

Schema coverage is 100% with zero parameters, so baseline is 3. The description adds no parameter details beyond stating no input needed, but it does mention the env var which is not a parameter.

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 'Return' and identifies the resource as 'active spec source' and 'all adapters'. It clearly distinguishes from sibling tools by specifying it returns source info and adapters, not spec content or analyses.

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 advises 'Call first in any session so the AI knows whether to expect markdown / GitHub / ... semantics', providing clear when-to-use guidance. It does not mention when not to use or alternatives, but the directive is direct and actionable.

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

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

No annotations provided, so description carries full burden. It discloses that argument values are never logged and describes the return structure. However, it doesn't explicitly state it's read-only or non-destructive, though that's implied.

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 informative but concise; it front-loads the purpose and uses clear structure. Every sentence adds value, though it could be slightly more compact without losing clarity.

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

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

Given no output schema, the description explicitly outlines the return structure: 'records_total, window_days, tools[], inactive[], markdown'. It covers all necessary context for a telemetry aggregation tool.

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

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

Schema description coverage is 0%, but the description explains both parameters: 'days (window, default 30)' and 'include_inactive (bool, default true)'. This adds meaning beyond the schema, which only has type and default.

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 aggregates tool-usage logs and lists specific metrics (most called, error rates, latency, unused tools). It uses specific verbs and distinguishes itself from sibling tools, which are all about spec analysis and testing.

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 tells when to use: 'Use when a user asks what the AI is actually using / which tools are slow / which tools are unused'. Also explains default arguments and return format, covering usage context comprehensively.

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

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

With no annotations provided, the description carries full burden. It discloses idempotency (refuses to overwrite unless overwrite=true) and the file's content purpose. It does not mention side effects or return values, but the key behavior is well-covered.

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

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

The description is two sentences: the first states the primary action and content, the second covers idempotency and optional parameter. It is front-loaded and contains no unnecessary words.

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

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

Given the simple interface (2 optional params, no output schema, no annotations), the description covers the essential aspects: what it creates, its behavioral constraints, and parameter roles. It could mention the template origin or expected outcome, but is sufficiently complete for an init tool.

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

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

Schema description coverage is 0%, so description compensates by explaining both parameters: 'project_name' labels the file, and 'overwrite' controls idempotent behavior. This adds meaning beyond the schema's type definitions.

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 creates a specific file (SPEC_PROJECT_ROOT/spec-knowledge.md) from a starter template, and distinguishes from sibling tools by noting that others lean on it indirectly via get_spec_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?

The description explains the idempotent behavior and the role of the overwrite parameter, and implies its use as the initial setup step for spec knowledge. However, it does not explicitly state when not to use it or provide direct comparisons to 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?

Discloses file write location, data ownership, idempotency (duplicate handling via timestamp update), and purpose of caching metadata. Explains return values. No annotations, so full burden borne well.

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 paragraph but each sentence adds value. Front-loaded with core purpose. Slightly long but not wasteful; could be tighter, but no redundancy.

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

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

Covers purpose, usage flow, parameter explanations, return values, and references sibling tools (get_coverage_matrix, get_drift_report). No output schema but return structure described. Complete for a mutation/link tool.

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

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

Schema coverage is only 33% (2 out of 6 params have descriptions). Description compensates fully: explains why spec_title/spec_source/spec_url are cached, ac_hash for drift detection, and roles of spec_id and test_node_id. Adds significant meaning beyond schema.

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

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

Clearly states the action: 'Record that a test verifies a spec.' Specifies verb (record link), resource (test-spec relationship), and details like file path. Distinct from siblings like auto_link_tests or get_coverage_matrix.

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?

Explicit timing guidance: 'Call this right after mk-qa-master.generate_test returns a node_id.' Explains why and when to pass optional params. Lacks explicit 'when not to use' but context is clear.

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

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

With no annotations, the description carries the full burden. It discloses the enumeration behavior, adapter-specific details, and filters. It is clearly a read operation, though it does not address authentication or error conditions.

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 (2 sentences), front-loaded with the main action, and uses no superfluous words. Every sentence contributes essential information.

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

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

The description covers the source modes, filters, and return format. Without an output schema, it adequately describes the output. Missing details like error handling or performance are acceptable for a simple list tool.

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

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

Schema coverage is 0%, so the description must explain parameters. It does so for all three: status with adapter-specific values, label as a string, and limit with a default. Label could have more detail, but overall adds significant meaning.

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

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

The description clearly states the action (Enumerate specs) and the resource (active source), with specific behaviors for two source types (markdown_local and github_issues), making it distinct from sibling tools like fetch_spec or parse_spec.

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

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

The description explains what the tool does but does not explicitly state when to use it versus alternatives. It lacks guidance on when not to use or compare to siblings like get_spec_context or fetch_spec.

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. It discloses parsing behavior: heading matching (case-insensitive, multiple languages), item extraction (numbered/bulleted), and return structure ({spec_id, title, acceptance_criteria[], roles[], preconditions[], _meta}). It also notes that 'roles + preconditions are placeholders in v0.1,' setting appropriate expectations. No contradictions with annotations (none 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?

The description is concise and well-structured. The first sentence states the purpose, followed by parameter guidance, and then return fields. Every sentence adds value, and there is no redundant information.

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

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

For a parsing tool with no output schema, the description explains input parameters (both optional, with clear use cases) and the return structure. It mentions version limitations (placeholders in v0.1). It does not cover error cases (e.g., both parameters provided, neither provided) or rate limits, but these are minor for this tool.

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

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

Schema description coverage is 0%, so the description compensates fully. It explains both parameters: spec_id (for active adapter) and raw_text (for ad-hoc parsing). It adds meaning beyond the schema by describing the return structure and the context of each parameter.

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

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

The description clearly states the tool's purpose: 'Extract structured acceptance criteria from a spec body.' It specifies the verb (extract), resource (acceptance criteria), and method (looks for headings matching given patterns). It distinguishes from sibling tools like fetch_spec (which retrieves raw spec) and analyze_spec_quality (which evaluates quality).

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

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

The description provides explicit guidance on parameter usage: 'Pass spec_id to use the active adapter, or raw_text to parse ad-hoc spec text without going through any source.' This clarifies when to use each parameter. However, it does not explicitly state when NOT to use the tool or compare to alternatives like fetch_spec for raw retrieval.

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

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

No annotations exist. The description discloses that it can call analyze_spec_quality internally and returns {markdown, actions[]}, but lacks details on side effects, performance, error handling, or implications of running the analysis (e.g., cost, 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?

Two sentences, front-loaded with core action, followed by usage guidance and output format. No redundant information; every sentence adds value.

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

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

Given no output schema and moderate parameter count (3, one nested), the description sufficiently explains functionality, input flexibility, usage scenarios, and output structure. Minor gap: no details on error conditions or input validation.

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 33% (only 'analysis' described). The description adds context: if 'analysis' omitted, it uses 'spec_id' and 'raw_text' to run analysis inline. This clarifies parameter usage but doesn't detail each parameter's format or constraints.

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

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

The description clearly states the tool's function: taking analyze_spec_quality output to produce a PM-facing markdown coach plan with rewrite suggestions. It distinguishes from sibling tools like analyze_spec_quality by noting it can run the analysis itself if needed.

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

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

The description explicitly says 'Use this when a user says how do I improve this spec or review my PRD', providing clear when-to-use guidance. It also clarifies that missing analysis triggers inline execution, but does not mention 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.