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 check action but does not explicitly state whether the tool has side effects, required permissions, or details about the registry snapshot. The behavioral transparency is adequate but not thorough.

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

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

The description is concise, front-loaded, and consists of two short sentences that convey essential information without fluff.

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

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

With no output schema and only one optional parameter, the description is adequate for basic understanding. However, it lacks details on return values or error conditions, which would improve completeness.

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

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

The schema coverage for parameters is 100%, and the description adds context about the 'lock' parameter being optional microservices.lock.json content. This meets the baseline for parameter 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?

Clearly states the verb 'check' and the resource 'locked module versions against the bundled registry snapshot'. The description distinguishes this tool from sibling 'plan_module_upgrade' by indicating it is a precursor action.

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

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

Explicitly recommends using this tool before plan_module_upgrade, providing clear context for when to use it. However, it does not discuss when not to use it or mention alternatives beyond the single sibling.

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 key behavioral trait 'without writing files' (dry run) but does not mention other aspects like permission requirements, rate limits, or what happens on failure. Since no annotations exist, the description carries full burden but is only partially sufficient.

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

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

Two sentences that efficiently convey purpose and usage. No redundancy, well structured.

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

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

With 3 parameters, no required fields, and no output schema, the description covers key aspects (non-destructive, preview nature, usage context). Could describe the return format more, but it's sufficient given the context.

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

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

All parameters have descriptions in the schema (100% coverage). The description reiterates 'template and selected modules' but adds no new meaning beyond the schema. Baseline 3 is appropriate.

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

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

Clearly states the action (compose), the resources (template and selected modules), and the output (checked app contract and lockfile plan). Includes explicit usage context 'before generate_project or deployment planning', distinguishing it from 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?

Provides explicit guidance on when to use the tool ('before generate_project or deployment planning'). However, it does not list alternative tools or explicitly state 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, the description reveals a key behavioral trait: it does not mutate remote state. However, it lacks details on idempotency, side effects, or plan lifecycle, leaving some behavioral gaps.

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

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

Two sentences, front-loaded with purpose, no redundant words, and a clear separation of purpose and usage guidance.

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

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

The description covers purpose, usage, and high-level output content (resources, checks, errors, etc.). It lacks explicit output format details but compensates with the plan's content description.

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 does not need to add parameter details. It adds no extra meaning beyond the schema, earning a baseline score.

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

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

The description clearly states the verb 'Create' and the resource 'local preview-deployment readiness plan', and distinguishes from sibling tool 'deploy_preview' by specifying it is a preparatory step.

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

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

Explicitly advises to use this tool before 'deploy_preview' and lists what it reviews (resources, checks, errors, warnings, approval steps). However, it does not compare with other sibling tools like 'run_checks' or 'validate_config', limiting exclusion 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?

No annotations provided, so description carries full burden. It declares the tool as 'mutating' and requires confirmation, but doesn't disclose side effects (e.g., whether it overwrites, creates, or destroys resources) or authorization needs beyond API key. Partial disclosure, but missing depth.

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 purpose, followed by critical usage guidance. Every sentence is necessary and no filler. Highly concise and well-structured.

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

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

Complex tool with 8 parameters and nested objects, but no output schema. Description covers prerequisites and confirmation but lacks detail on return values, effects on state, or how parameters like modules and config influence deployment. Adequate for basic correct usage but not fully complete.

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

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

Schema description coverage is 100%, so schema already documents all 8 parameters. The description adds no additional meaning beyond the schema; it reiterates the confirmation requirement but doesn't explain parameter interactions or provide examples. Baseline 3 is appropriate.

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

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

Description explicitly states 'Prepare a remote preview deployment through the microservices.sh control plane', clearly identifying the verb (deploy preview) and resource (remote preview via control plane). It distinguishes from sibling create_preview_plan by specifying that the plan should be created first.

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: 'call create_preview_plan first and only proceed after human review.' Also states the required confirmation value, providing clear preconditions and decision criteria.

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 bears full responsibility. It discloses the key behavior: in-memory generation without file writing, suitable for inspection. However, it does not mention potential errors or limitations (e.g., what happens with an invalid template ID).

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. The first gives the core action and constraint; the second clarifies the use case and what the tool is not for. 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?

The tool has 3 optional parameters, no required ones, and no output schema. The description explains the generation purpose and inspection use case. It is mostly complete but could mention what happens on invalid input or error states.

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

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

Schema coverage is 100%, with each parameter having a description. The description adds little beyond the schema—it restates optionality for templateId and lists module examples. With high schema coverage, baseline 3 is appropriate; the description provides minimal extra 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 generates project source files in memory for agent inspection, using a specific verb ('generate') and resource ('project source files'). It distinguishes itself from sibling tools by emphasizing it does not write files.

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

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

The description explicitly says when to use this tool ('to review planned source, docs, migrations, and config before creating or editing a local project') and what not to expect ('does not write files'), providing clear guidance on its context.

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

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

With no annotations, the description bears full responsibility. It indicates read-only access ('read'), but does not detail error responses, rate limits, or other behaviors. For a simple status retrieval, this is sufficient but could be more 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 consists of two concise sentences that front-load the purpose and immediately follow with usage guidance. Every word adds value with no redundancy or filler.

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

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

Given no output schema and a simple read operation, the description adequately covers the tool's purpose and usage. However, it omits mention of the format of the returned data or potential error scenarios, leaving some gaps.

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

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

Schema coverage is 100% so all parameters are described in the input schema. The tool description adds no new parameter details beyond what the schema provides, meeting the baseline 3 but not exceeding it.

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 'Read a remote preview deployment status' providing a specific verb and resource. It distinguishes from siblings by explicitly linking to deploy_preview and listing use cases (poll status, inspect errors, retrieve metadata).

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 explicit guidance: 'Use this after deploy_preview to poll status, inspect errors, or retrieve deployment metadata.' This tells when to use it and for what purposes, effectively differentiating from other tools.

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

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

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It states 'Return ... documentation' but does not mention that the tool is read-only, safe, or requires any authentication or permissions. It lacks explicit transparency about side effects or limitations.

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

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

The description is two sentences: the first defines the tool's purpose, the second gives usage guidance. Every sentence adds value with no redundancy. It is appropriately front-loaded with core functionality.

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

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

With one parameter, no output schema, and no annotations, the description is adequate but not complete. It covers purpose and usage, but omits return format or any behavioral context (e.g., read-only). For a simple tool, it meets minimum viability but has gaps.

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

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

The schema describes 'moduleId' with 100% coverage. The description adds an example ('booking or payment'), which provides extra context but does not significantly enhance semantic understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Return an LLM-readable documentation page for a module', with a specific verb ('return'), resource ('documentation page'), and scope ('for a module'). It also lists contents ('rules, implementation notes, agent guidance'), distinguishing it from siblings like 'list_module_docs' which likely list titles only.

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 instructs 'Use this before coding against a module contract,' providing a clear context of use. However, it does not explicitly mention when not to use it or name alternative tools (e.g., 'inspect_module') for comparison.

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 explicitly states that the tool does not 'expos[e] secret values,' which is a key safety trait. The verb 'report' implies no side effects. However, it does not mention permissions or error conditions, which would elevate it further.

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 purpose and constraint, second gives usage context. No wasted words, front-loaded with the most 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?

For a tool with 3 optional parameters and no output schema, the description sufficiently indicates the output (names and status) without detailing structure. It covers the essential usage context, but could be more complete by describing the response format.

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 each parameter has a description in the schema. The tool description adds no additional meaning beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

The description clearly states it 'report[s] required secret names and configured/missing status,' which is a specific verb-resource pair. It also distinguishes itself from siblings by noting its use case 'before deployment planning or remote preview deploys,' differentiating it from tools like 'deploy_preview' or 'get_deployment_status.'

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

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

The description explicitly says 'Use this before deployment planning or remote preview deploys,' providing clear context for when to invoke the tool. It lacks explicit when-not-to-use guidance or comparison to alternatives, but the context is sufficient for an agent to understand its preparatory role.

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 inspection scope in detail but does not explicitly state that the operation is read-only or disclose any side effects, permissions, or rate limits. This is adequate but not thorough.

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

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

The description is two sentences with no redundancy. The first sentence defines functionality, the second gives usage context. 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?

The tool has one parameter, no output schema, and no nested objects. The description explains what the tool does and when to use it, but it does not describe the structure or content of the returned data, which would improve completeness.

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

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

The input schema already has 100% coverage with a clear parameter description including examples. The tool description adds no additional semantic value beyond restating the purpose, so a baseline score of 3 is appropriate.

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

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

The description clearly states 'Inspect one module contract in detail' with a specific list of included aspects (permissions, hooks, etc.), and distinguishes it from siblings like 'get_module_doc' by emphasizing depth. The tool's purpose 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?

The description explicitly advises 'Use this before editing or adding a module', providing clear context. However, it does not mention when not to use it or suggest alternatives, which would strengthen the 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 disclose behavior. It describes the tool as inspecting details, implying read-only, but does not explicitly confirm non-mutating nature, error conditions, or output format. Adequate but lacking full transparency.

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

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

Two sentences, no fluff. Information is front-loaded: first sentence describes function, second sentence gives usage context. Every sentence 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?

Given low complexity (single parameter, no output schema, no annotations), the description provides sufficient context: what the tool inspects, when to use, and parameter guidance. Could mention return behavior but not critical.

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% but the description adds value by providing an example ('booking-sveltekit') and clarifying the source of the template ID ('returned by list_templates'). This goes beyond the schema's description.

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

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

The description specifies the verb 'inspect', the resource 'app template contract', and lists inclusive details (supported modules, configuration, metadata, generation behavior). It also differentiates from siblings by stating when to use this tool, making purpose distinct.

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

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

Description explicitly states usage context: 'Use this before composing or generating a project from a specific template id.' This provides clear guidance on when to invoke, though it does not mention when not to use or list 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 adds the trait 'LLM-readable' and indicates the docs are for 'module implementation guidance.' However, it does not disclose any behavioral details like error handling or pagination, but the simplicity of the tool makes this sufficient.

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 the action, no wasted words. Perfectly sized for a simple list tool.

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 no parameters, no output schema, and is a straightforward list operation, the description provides all necessary context: what it does, when to use it, and how it relates to siblings. No 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?

There are no parameters, so the description need not add any. The schema coverage is 100% (trivially). Baseline for 0 parameters is 4.

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

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

The description clearly states it lists LLM-readable documentation pages for module implementation guidance. It distinguishes from the sibling get_module_doc by indicating it's for discovery before retrieving a specific doc.

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 to use this before get_module_doc or before making changes to generated source, providing clear when-to-use guidance and mentioning an alternative.

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 bears full responsibility for behavioral disclosure. It only describes what the tool lists without mentioning any behavioral traits like read-only status, authentication requirements, side effects, or potential limits. The lack of behavioral context is a significant gap.

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

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

Two sentences front-load the purpose and usage context. Every word adds value, with no repetition or fluff.

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 zero parameters and no output schema, the description provides essential information (what is returned and when to use it). However, it misses details like whether the list is exhaustive or paginated, but for a simple discovery tool this is adequate.

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

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

The tool has no parameters, and schema coverage is 100%. The description does not need to add parameter information. The baseline is 4, and the description appropriately avoids redundant parameter details.

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

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

The description uses a specific verb ('List') and clearly states the resource ('available verified microservices.sh modules') along with the fields returned (ids, categories, summaries, versions, maturity status). It distinguishes itself from siblings by being a discovery tool before other actions.

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

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

The description explicitly states 'Use this to discover production building blocks before inspect_module, compose_app, or plan_add_module.' This provides clear context and sequence, though it does not mention scenarios where the tool should not be used.

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. It states the tool lists templates with IDs and summaries, implying a read-only operation. While it does not explicitly declare idempotency or side effects, the simple nature of the operation (listing) makes it reasonably transparent. A slightly more explicit mention of being read-only would improve 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 consists of two concise sentences, front-loaded with the main action and output, followed by usage guidance. Every sentence adds value 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?

Given the low complexity (0 parameters, no output schema), the description adequately covers what the tool does and when to use it. It mentions the output includes IDs and summaries, which is sufficient for selecting a template. Could be more specific about output format, but overall 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 no parameters, so schema coverage is 100%. The rubric gives a baseline of 4 for 0 parameters. The description does not need to add parameter info since there are none, so this score is appropriate.

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

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

The description clearly states the tool lists available microservices.sh app templates, including template IDs and summaries. It distinguishes itself from sibling tools by explicitly mentioning its role as a prerequisite for inspect_template, compose_app, generate_project, and run_checks.

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 the agent to use this tool before sibling tools like inspect_template, compose_app, generate_project, or run_checks when choosing a foundation for a new Cloudflare app. This provides clear context on when and why to use this 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?

With no annotations, the description carries the full burden. It discloses non-destructive behavior ('without writing files') and mentions 'approval-gated' and 'review gates', but does not detail side effects, required permissions, or behavior when the lock file is absent.

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

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

Two sentences, front-loaded with the verb and resource, no fluff. 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 3 params, nested objects, and no output schema, the description explains the tool's purpose and output concept (intended changes, review gates). It could describe the return format, but is largely complete for a planning 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 descriptions for all parameters. The description adds little beyond confirming 'moduleId' as a selector and 'lock' as optional content. As per calibration, baseline 3 is appropriate when schema descriptions are already sufficient.

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 plans an approval-gated module addition and reports intended changes without writing files, distinguishing it from write operations. However, it does not explicitly differentiate from the sibling tool 'plan_module_upgrade', which serves a similar purpose for upgrades.

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 when to use (planning without actual modification) but does not provide explicit when-not-to-use guidance or compare with alternatives like 'plan_module_upgrade'. The context is clear but lacks 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?

Without annotations, the description carries the full burden. It discloses that the tool reports approval gates, compatibility notes, and lockfile impact, indicating a read-only planning operation. However, it does not explicitly state that it is non-destructive or idempotent, leaving some ambiguity about 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 two sentences: the first states the purpose and outputs, the second gives usage guidance. It is front-loaded, efficient, and contains 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?

Given four optional parameters and no output schema, the description covers the key outputs (approval gates, compatibility, lockfile impact) but does not specify return format or further behavioral details. It is mostly complete but could benefit from mentioning the preview nature or safety of the operation.

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

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

Schema coverage is 100% with each parameter having a description. The tool description does not add additional meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's action: 'Plan a module version change and report approval gates, compatibility notes, and lockfile impact.' It distinguishes this from sibling tools like 'plan_add_module' (which adds a module) and 'check_updates' (which checks for updates), making its purpose unique and specific.

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 includes 'Use this before applying a module upgrade,' providing clear context for when to use the tool. While it does not explicitly state when not to use it or list alternatives, the sibling tool names imply alternatives (e.g., 'plan_add_module' for adding modules), giving 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 carries the full burden. It describes the behavior (running checks) but does not disclose potential side effects, permissions required, or output format, leaving some behavioral gaps.

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

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

Two sentences: first defines the tool, second gives usage context. No redundant words, front-loaded, and efficient.

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

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

Given the tool's complexity (3 params, no output schema), the description covers the overall goal and timing well. It lacks detail on return values or error handling, but for a check tool this is acceptable.

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 baseline is 3. The description does not add significant meaning beyond the schema; it merely restates the parameters' general purpose without elaboration.

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 ('run local contract and readiness checks'), the object ('template/module composition'), and the purpose ('verify module compatibility, generated artifacts, and operational guardrails'), effectively distinguishing it from 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?

It explicitly advises using this 'before deployment planning', providing clear context. However, it does not specify when not to use it or mention alternatives, which would strengthen 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?

No annotations are provided, so the description bears full responsibility. It states the tool is non-destructive ('before side effects') and describes its validation scope, but lacks details on auth requirements, response format, or error behavior. 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?

Two sentences, no filler, front-loaded with purpose. Each sentence adds unique value: first defines action, second explains benefit.

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 three optional parameters (one nested object), the description covers purpose and usage well. It misses specifying return format (e.g., success/error list) but is sufficient for a validation check tool.

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

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

Schema description coverage is 100%, so each parameter already has a description. The tool description adds context ('validate before generation') but does not provide new semantic detail beyond the schema, leading to a baseline score of 3.

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

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

The description explicitly states the tool validates a template, module list, and configuration object, using specific verbs and resources. It clearly distinguishes from sibling tools like compose_app or deploy_preview by noting it is a pre-check before side effects.

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 a clear usage scenario ('before generation or deployment') and lists what it catches (unsupported modules, missing settings, invalid config). It does not explicitly state when not to use or mention alternatives, but the context is sufficiently clear.

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