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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a meaningful behavioral trait beyond annotations: it refuses certain inputs (placeholders/compute_local) and only handles stamped contracts. This is useful context that annotations do not provide. No contradiction with annotations.

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

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

The description is two sentences with zero wasted words. The primary action is front-loaded, and the refusal condition is stated in a compact second sentence. It is exemplary in brevity.

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

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

While an output schema exists (which may cover return values), the description fails to explain the purpose of any parameter, the meaning of 'stamped contract', or the expected input format. For a tool with five optional parameters and no schema descriptions, this leaves agents under-equipped. The refusal condition is useful, but the absence of parameter semantics makes the tool contextually incomplete.

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

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

The input schema has 0% description coverage for its five parameters (mode, path, scope, bucket, json_text), so the description must compensate, but it does not mention any parameter or its meaning. Agents receive no guidance on what values to provide, making correct invocation nearly impossible without external knowledge.

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 ('Extract') and resource ('stamped contract.hash'), and specifies a constraint that it only operates on stamped contracts and refuses placeholders/compute_local. This clearly distinguishes the tool's purpose and is unlikely to be confused with any sibling, which are unrelated (e.g., smoke_test_agent, diagnose_error).

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 context on when to use the tool (to extract stamped contract.hash) and explicitly lists refusal conditions (placeholders/compute_local), which serves as a negative usage guideline. It does not name an alternative tool for those cases, but the guidance is clear enough for an agent to decide against using this tool for disallowed inputs.

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 read-only, idempotent annotations, the description adds real behavioral context: it conditionally folds Detective URL templates when req_id/chat_id are present and explicitly states that Hub scraping is not performed. This is meaningful and does not contradict the 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 terse, front-loaded sentences cover the core mapping behavior, the conditional link behavior, and a key exclusion. There is no filler, repetition, or unnecessary detail.

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 10 optional parameters, the description explains the central behavior and one important conditional, and an output schema exists to document return values. Still, it does not clarify which parameters should be populated or how the mapping consumes them, so an agent must infer a significant part of invocation.

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 only names and empty-string defaults, so the description's clarification that req_id/chat_id trigger detective_links is a genuine addition. But the remaining eight parameters are only loosely implied to be 'error signals,' with no specifics about how they are used, leaving a notable coverage gap.

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 names a concrete action and object ('Map error signals to failure_class + errors.md anchor'), so an agent can tell what the tool accomplishes. The notes about Detective URL templates and not scraping Hub further sharpen scope, but it does not explicitly distinguish itself from sibling diagnostic tools like doctor.

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 purpose sentence implies this should be used when error signals need mapping to a failure class and errors.md anchor, and 'Does not scrape Hub' is a useful exclusion. However, there is no explicit 'use when...' or 'instead of...' guidance, and no alternative sibling is named, so routing is largely left to inference.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context that env/compat/cache fold related validation tools and includes an operational warning ('Do not grep the Zeus engine tree for first green'), which is useful, but it does not clarify what the output looks like or what 'first green' means.

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 compact and front-loads the detail values early. It avoids fluff, and each section adds some information, though the phrasing 'fold' and the telegraphic 'Health / doctor.' make it less polished than ideal.

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 optional-parameter tool with read-only and idempotent annotations plus an output schema, the description is mostly sufficient. The main gaps are ambiguity about what 'fold' means and the unexplained reference to 'first green,' as well as no explicit differentiation from the diagnostic sibling tools.

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

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

The single parameter detail has no schema description and no enum, but the description supplies the allowed values: health | env | compat | cache | all. It also maps env/compat/cache to validate_env, compat_check, and semantic_cache_status, giving the parameter more meaning than the schema alone. It does not spell out what each value returns, though an output schema exists.

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 opens with a noun fragment, 'Health / doctor,' which mostly restates the tool name and the domain rather than stating a specific verb and resource. It does enumerate detail options (health | env | compat | cache | all), which give partial purpose, but it does not distinguish doctor from sibling tools like diagnose_error, readiness_check, or smoke_test_agent.

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

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

The description provides a follow-up workflow condition ('If the user already gave a Zeus URL or sample name, next call set_prereq...'), but it does not say when to use doctor versus the diagnostic sibling tools. The line about env/compat/cache folding validate_env, compat_check, and semantic_cache_status hints at coverage but never explicitly states selection criteria or exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a behavioral contract beyond the annotations: the instruction to call only the recommended tool next and the conditional recommendation logic. It does not add side-effect details because none exist, but it does add operational behavior that is not in the structured fields.

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 short paragraphs with no filler. The first sentence front-loads the purpose, and the second paragraph delivers precise usage rules. Every sentence earns its place, and the structure is easy to scan.

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 zero parameters, an output schema exists, and annotations cover safety, the description is complete. It states what the tool does, when to use it, how to sequence calls, and which sibling alternatives to prefer. There are no missing pieces that an agent would need to invoke it 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?

This tool has zero parameters and the input schema is empty, so there is nothing to explain. The baseline for 0 params is 4, and the description does not need to compensate for any schema gaps. It mentions external context (URL/bucket, prereqs) but that is not parameter input, so no further semantic detail is required.

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 resource ('single current checklist blocker + recommended Helper tools'), and it distinguishes itself from siblings by framing itself as a coach that recommends the next step. It clearly tells the agent what the tool produces without needing to open the schema.

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 when-to-use guidance: 'Call only the recommended tool next', a conditional rule for set_prereq when URL/bucket is named and prereqs are unset, and a preference for zeus-helper:// + readiness_check / smoke_test_zeus over hand-rolled curl. This is rich, actionable guidance that selects among siblings (set_prereq, readiness_check, smoke_test_zeus).

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 provide idempotentHint and destructiveHint, and the description adds useful behavioral context: 'Never returns secret values' and 'Emits failure_class + next_action on red paths.' This goes beyond the annotations. However, it does not disclose any side effects associated with the update_checklist parameter, despite readOnlyHint being false.

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 tightly written sentences: the first names the core scope, and the second adds safety and failure-output behavior. There is no filler, and the main purpose 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?

The output schema covers return structure, and annotations cover idempotency and destructiveness. Still, the definition omits usage guidance relative to several similar siblings and leaves the update_checklist parameter semantically ambiguous, so the overall context is 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 0%, and the description does not mention update_checklist at all. The name and default true imply some update behavior, but the meaning of 'checklist' and the effect of setting it to false remain unexplained. With low schema coverage, the description needed to compensate and did not.

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 names specific resources and scopes: 'healthz/readyz/version, auth, bootstrap, chat_request.' This clearly identifies what the tool checks. However, it does not explicitly differentiate readiness_check from siblings like smoke_test_zeus or diagnose_error, so it stops short of full sibling distinction.

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

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

The description gives no guidance on when to use readiness_check versus the many sibling tools such as smoke_test_zeus, doctor, or diagnose_error. There are no conditions, exclusions, or alternative recommendations, leaving the agent to guess based on the name alone.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds a meaningful external behavior—'Does not call Zeus'—which is not in the annotations, but it omits other behavioral context like prerequisites or side effects. Given the annotation coverage, the added value is modest.

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 short sentences with no padding, and the core purpose is front-loaded. Each sentence earns its place, though the terseness borders on under-specification. Overall, it is well-structured 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?

With three parameters, no schema descriptions, and only this terse description, the tool is under-specified for an agent to call it correctly. The presence of an output schema helps with return values but does not compensate for missing parameter semantics. The description reads as an internal note rather than a complete tool contract.

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

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

Schema description coverage is 0%, and the tool description provides no explanation of the three parameters (qps, intent, needs_llm). An agent cannot infer how to set 'intent' or when to supply 'qps' or 'needs_llm' from either source. This is a critical gap for a tool with a required 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 states a specific verb ('Pick') and resource ('Direct vs agent surface'), and names a trace class, which gives a clear sense of the tool's decision-making role. It also explicitly notes 'Does not call Zeus,' differentiating it from Zeus-related siblings. However, 'Trace-Class (ZDH-18)' is unexplained and may confuse an agent unfamiliar with the domain.

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

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

There is no explicit guidance on when to use this tool versus alternatives. The only hint is 'Does not call Zeus,' which implies it is not for workflows requiring Zeus, but it does not name sibling tools or provide selection criteria. This is insufficient for effective routing.

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

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

Annotations declare destructiveHint: true, so the description carries the burden of explaining what gets destroyed (e.g., overwriting files in target_dir). The description says only 'Write a ZeusRuntime middle-man' with no mention of side effects, safety, or reversibility, adding no behavioral context beyond the annotation.

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

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

The description is extremely concise at three lines, front-loading the core action and then constraints. Every sentence earns its place, though it sacrifices completeness for brevity.

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

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

Given the tool has 5 parameters, a destructive hint, and no schema coverage, the description is severely incomplete. It omits parameter semantics for force and project_name, does not explain return values (though an output schema exists), and fails to mention overwrite behavior. A scaffolding tool typically needs to state what it creates and overwrites.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies app_kind (cli or api) and coding_language (python only) but leaves force, project_name, and target_dir (beyond being required) unexplained. This is inadequate for a tool with 5 parameters and no schema documentation.

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 verb and resource ('Write a ZeusRuntime middle-man') but is vague about what scaffolding entails. It differentiates from use_sample/demo_travel_sample but not from start_project or other potential scaffolding siblings, leaving the exact purpose ambiguous.

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 excludes UI demo use ('UI demos use use_sample / demo_travel_sample, not this tool') but provides no positive when-to-use guidance and no differentiation from start_project or other tools that might create projects. The constraints on app_kind and coding_language are useful but not usage context.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description discloses that values are persisted and override environment defaults, that secrets are not stored, and that only presence flags are used for credentials/LLM key. This adds meaningful behavioral context that the annotations alone do not provide, with no contradiction.

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 compact and front-loaded: purpose, security boundary, usage context, and persistence behavior are each covered in a few short lines without fluff. Every sentence adds necessary operational information, and the structure is scannable.

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 11 optional parameters and 0% schema coverage, the description handles the core usage well: what to store, what not to store, when to pass Zeus context, and how flags behave. It falls slightly short on fully explaining the remaining parameters (mode, role, collection, auth_mode), though an output schema exists and no parameters are required.

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

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

Schema description coverage is 0%, so the description must compensate. It adds valuable semantics for zeus_url/bucket/scope and clarifies the has_* presence flags, but it does not explain the meaning of mode, role, collection, or auth_mode. With 11 parameters, this partial coverage leaves a clear gap even though the most important parameters are addressed.

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/resource ('Store non-secret prereqs for readiness') and immediately disambiguates what it does not do ('does not store password/token values'). It ties the stored values to downstream consumers ('readiness/doctor'), making it distinct from sibling tools like readiness_check or doctor.

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 when-to-use guidance: pass user-named zeus_url/bucket/scope instead of Helper localhost defaults, and put real secrets in environment variables. It also explains the override behavior ('Persisted values override MCP host ZEUS_* env defaults') and limits the presence flags to credentials/LLM key, leaving no ambiguity about when this tool should be called.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds some behavioral context: it requires a specific client version and LLM key, and it may return a guide-only docker compose next_action. However, it does not explain side effects, failure modes, or what 'run_turn' entails. No contradiction with annotations.

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

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

The description is short and front-loaded with the core dependency, but the second sentence is dense and somewhat cryptic. It earns its place by adding conditional behavior, but the phrasing is awkward and could be clearer. Not overly verbose, but not 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?

Given there is an output schema, the description needn't explain return values, but it still lacks essential context: what the tool actually does, when to use it, and what the parameters mean. The dependency and conditional behavior are useful but incomplete. An agent would struggle to invoke this correctly without more information.

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

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

Schema description coverage is 0%, so the description must compensate. It does not explain the 'question' parameter or 'update_checklist' parameter at all. The description's mention of 'run_turn' and 'next_action' hints at behavior but not parameter meaning. With 0% coverage and no param explanation, this is a significant gap.

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 says 'One ZeusRuntime run_turn' but does not clearly state what the tool does. It mentions a dependency and a conditional behavior about docker compose, but the core action is vague. It does not distinguish itself from siblings like smoke_test_zeus or diagnose_error.

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 a conditional behavior (if client missing, return guide-only docker compose next_action) but does not explicitly state when to use this tool versus alternatives. No clear context for when an agent should invoke smoke_test_agent over smoke_test_zeus or diagnose_error.

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

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

Annotations indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false, which is a mixed safety profile. The description adds 'without LLM' to clarify that no language model is invoked, but doesn't disclose what happens during the smoke test (e.g., whether it creates or modifies resources), or what the readiness check entails. There is no contradiction, but the description is thin on behavioral details.

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

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

The description is a single sentence with essential information: it identifies the tool's purpose and the endpoint. It is front-loaded with the key action 'Smoke Zeus without LLM' and includes a specific HTTP endpoint, which is efficient. No fluff or repetition.

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 a simple signature (1 optional param), annotations provide some safety context, and an output schema exists, so the description does not need to detail return values. However, given the existence of a sibling 'smoke_test_agent', the description should clarify the difference, and it doesn't explain what 'readiness' means in this context or what 'smoke' entails beyond an HTTP call. It is adequate but with 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 has one optional parameter 'update_checklist' with 0% description coverage in the schema itself. The description does not explain it either, but with only one parameter and no required params, the burden is low. The parameter name is self-explanatory, and the description's focus on 'readiness' and 'describe' implies the checklist is updated, but explicit clarification would be better.

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

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

The description states the tool performs a 'smoke test' on Zeus and mentions a specific endpoint (POST /v2/{bucket}/{scope}/describe), which is specific. However, it does not differentiate from sibling tools like 'smoke_test_agent' – the name 'smoke_test_zeus' is a tautology, and the description doesn't clarify what makes it distinct from the agent variant.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose smoke_test_zeus over smoke_test_agent or other diagnostic tools. The context signals show no explicit usage context, so an agent would have to infer from the name.

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

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

Annotations declare destructiveHint=true, readOnlyHint=false, idempotentHint=false. The description adds value by explaining the 'reset' behavior and the gating conditions for multi-agent scenarios (e.g., 'gated until single-agent smokes green unless force_multi=true'). It also clarifies the default ('single-agent default') and the role of force_multi. No contradiction with annotations; the 'reset' aligns with destructive behavior.

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 structured with a bullet list for samples, which improves readability. The main purpose is front-loaded, followed by sample details and then gating rules. It is relatively concise given the information it conveys, though the separate paragraphs could be tightened. It avoids redundancy and wastes little space.

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 that the schema is minimal and annotations are present, the description covers the key behavioral aspects: the reset/start capability, the sample variations, gating for multi-agent goals, and default values. It does not describe return values, but an output schema exists, so that is acceptable. It could be more explicit about what 'coaching checklist' entails or prerequisites like what 'smokes green' means, but these are 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?

The input schema has zero descriptions, so the description must compensate. It does explain the sample parameter extensively (listing values and their UI/scaffold implications) and mentions goal=multi and force_multi. However, it omits an explicit explanation of what 'goal' does beyond the implicit 'single-agent' vs 'multi', and the 'force_multi' parameter is only mentioned in the context of gating. It adds some meaning but not complete coverage for all three parameters.

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

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

The description states a clear action: 'Start or reset first-app coaching checklist'. It defines the verb (start/reset) and resource (coaching checklist), and lists sample variants. However, it does not explicitly differentiate from sibling tools like use_sample or scaffold_app; it mentions them inside the sample descriptions but not as alternative overall purposes. The core purpose is understandable, but the term 'coaching checklist' is somewhat ambiguous without further 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 provides concrete guidance on when to use this tool vs alternatives: it lists sample options and notes that travel and beer can be achieved via use_sample, and api via scaffold_app, implying start_project is the primary entry point. It also explains gating for multi-agent goals (goal=multi or sample=yelp) and the force_multi escape. This is useful, but it does not explicitly state 'use this tool when you want to set up a coaching checklist' or list exclusion criteria beyond the sample paths.

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 cover idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds that it sets an environment variable (DEMO_TRAVEL_SAMPLE_DIR) and writes a catalog UI in beer mode, and that beer mode uses 'no LLM; find→get'. This gives some behavioral color beyond annotations. But it doesn't disclose side effects like directory creation, network cloning, or permission needs. Since annotations carry the safety profile, a 3 is appropriate.

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

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

The description is compact and uses line breaks to separate the two sample modes and the project_name note. The most important parameter (sample) is front-loaded. There is no wasted prose, though some jargon ('Direct catalog', 'find→get') could be clearer.

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 an output schema present and idempotency annotations, the description covers the basic invocation path. However, given 5 parameters with zero schema descriptions, the description should explain all parameters to be fully complete. It also doesn't reference sibling tools to help the agent choose between them. For a tool with two main modes, it is adequate but not comprehensive.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the 'sample' parameter's allowed values ('travel'/'beer') and their distinct behaviors, and it documents 'project_name's default behavior. However, it leaves 'parent_dir', 'sample_dir', and 'clone_if_missing' completely unexplained, which is a significant gap for full 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?

The description states the tool sets up UI samples for either 'travel' or 'beer' templates, with concrete actions ('locate/clone demo_travel_sample' vs 'write demo_beer_sample Direct catalog UI'). It distinguishes two modes based on the 'sample' parameter. However, the initial phrase 'UI sample: travel clone or beer Direct template' is cryptic and lacks a clear overall statement of function, missing the clarity of a top-tier explanation.

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 conditional guidance ('sample=travel' vs 'sample=beer') and notes that 'Extra travel-only phases stay on travel_golden_path (travel toolset)', implicitly steering extra travel work to a sibling toolset. However, it never explicitly states when to prefer this tool over siblings like scaffold_app or start_project, nor lists exclusion conditions. Usage is implied rather than fully explicit.

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