specpack

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

Annotations declare readOnlyHint=true and openWorldHint=true, and the description adds meaningful behavioral context: it takes 10-40s, consumes one AI draft, and returns assumptions. It also warns to review assumptions before calling generate_spec. 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?

Three sentences, all information-dense and front-loaded. The core action and return values come first, then cost/latency, then usage routing. No filler.

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

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

For a tool with 2 params, full schema coverage, and no output schema, the description covers the key operational facts: what it does, what it returns, how long it takes, its cost, and when to use it. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds context about the description parameter (plain-language project description) and the optional type parameter (force the project type), but doesn't add much beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb ('fill the whole questionnaire'), the resource (the server's AI/Claude), and the input (plain-language project description). It also names the return values (project type, answers, assumptions), which distinguishes it from siblings like get_questionnaire.

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

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

Explicitly says when to use this tool vs get_questionnaire ('Prefer answering get_questionnaire yourself when you already know the project; use this when you only have a one-line idea') and names the next step (generate_spec). This is clear routing 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?

Beyond the all-false annotations, the description adds real behavioral context: deterministic byte-for-byte output, value encoding rules, quota consumption ('Uses one spec from the quota'), and default file placement at the repository root. It does not disclose overwrite behavior, but nothing contradicts the annotations, and the quota note aligns with the non-idempotent hint.

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 dense sentences cover the core transformation, determinism, value encoding, defaults, target location, and quota cost with no filler. The list of specification areas is long but earns its place by conveying the full scope of the generated output.

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

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

For a tool with nested answers, enums, no output schema, and quota side effects, the description covers most operational facts: what is generated, which files are returned by default, where to write them, and the quota cost. The main gap is that the return shape (e.g., mapping of file name to content) is not specified, but the default file names and 'returns the requested files' provide enough orientation 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?

With 67% schema coverage, the schema already describes files and answers, but the description adds crucial semantics for how answer values must be encoded (single option value, array for multiselect, boolean, number). It also clarifies the files default. The required 'type' enum is not further explained, though the enum itself is fairly self-descriptive.

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 a precise transformation: questionnaire answers into a complete build specification and matching agent files. It is clearly distinct from siblings like get_questionnaire or draft_answers, which collect or edit answers rather than generate the spec output.

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

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

The description implies this is the post-questionnaire generation step ('Turns questionnaire answers...') and describes default files and quota behavior, but it never explicitly names when to prefer this tool over siblings or when not to use it. The prerequisite of having answers from get_questionnaire is implied rather than stated as a routing instruction.

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, so the description doesn't need to restate that. The description adds useful behavioral context: the order of questions, the structure of each question (id, type, options, condition), and the fallback behavior for skipped questions. This goes beyond the schema and annotations, though it doesn't detail the exact response format or pagination (likely not needed for a single questionnaire).

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 explains the output structure, the question format, the conditional logic, and the downstream usage in a few sentences. Every sentence adds value, and the most important information (what the tool returns) is front-loaded.

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

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

For a simple read-only tool with one parameter and no output schema, the description is quite complete. It covers the question structure, the ordering, the conditional behavior, and the next step (generate_spec). The only minor gap is that it doesn't explicitly state the response format (e.g., JSON array), but the description of question fields implies it. Given the low complexity, this is sufficient.

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

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

Schema coverage is 100%: the only parameter 'type' is fully described with an enum of project types. The description adds context about what the parameter represents (project type) and how it affects the returned questions, but the schema already provides the enum and description. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: retrieving the questionnaire for a project type, with a specific structure (universal questions first, then type-specific ones). It distinguishes itself from siblings by mentioning the downstream use (pass answers to generate_spec) and the required fields, making it clear this is a read-only questionnaire retrieval 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 provides clear context on when to use this tool: when you need the questions for a project type. It also gives guidance on what to do after retrieving the answers (pass to generate_spec) and notes that only project_name and project_description are required. However, it doesn't explicitly state when NOT to use it or name alternatives like list_project_types, though the context signals show siblings that are clearly different.

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 readOnlyHint annotation already signals a safe read operation, and the description adds useful behavioral context by specifying what is included ('specs and AI drafts') and the fallback scoping to the address. This goes beyond the annotation without contradicting it.

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

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

The description is a single sentence that front-loads the core purpose and adds only the necessary scoping detail. There is no redundant language or repetition of the name or title.

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 no-parameter, read-only usage lookup, the description is nearly complete: it names the data returned and the scope. It doesn't describe the exact return shape, but with no output schema and a simple resource, the provided context is sufficient for an agent to invoke 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 tool accepts zero parameters, so there are no parameter semantics to document. The description correctly explains what the tool reports, and with schema coverage at 100% there is no hidden parameter information an agent would miss.

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 resource ('plan and quota usage') and scopes it to the API key or address, and it is easy to distinguish from the sibling tools which operate on different resources. It lacks an explicit imperative verb, but 'Current plan and quota usage' is unambiguous enough.

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

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

The description provides clear context for when the tool applies: it reports usage for the API key, or for the address when no key is set. It does not explicitly name alternatives or exclusions, but the sibling tools are distinct enough that an agent is unlikely to confuse them with a usage lookup.

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?

readOnlyHint=true covers the safety profilecluster, and openWorldHint=false already signals a bounded set. The description adds the finite list of types and the 'with what each covers' output shape, which is useful context beyond the annotations. It does not mention more behavioral details, but those are less critical for a read-only zero-parameter 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?

One sentence with no filler. It front-loads the resource ('the project types the spec generator knows') and packs the relevant enumeration and content promise into a compact statement.

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, read-only enumeration tool, this description is complete. It tells the agent exactly what set of values will be returned, that each has a coverage explanation, and how it relates to the spec generator. No output schema or additional detail is necessary for a tool this simple.

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 baseline of 4 applies. The empty input schema already fully documents that no arguments are required. The description does not need to add anything further here.

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 resource: the project types known to the spec generator, and enumerates them explicitly. It lacks an imperative verb like 'List', but the noun-phrase framing is unambiguous. The mention of the spec generator differentiates it from the drafting/generation 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?

The description implies the tool should be used when the agent needs the valid set of project types and what each coversahan. However, it provides no explicit context about when to choose this over generate_spec or other siblings, nor any direct guidance on how the returned types should be used.

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