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 already indicate destructiveHint=true and readOnlyHint=false, and the description adds useful behavior beyond that: writing files, asking before writing when no Zeus URL is stored, and a security warning not to pass a password. It does not explain force/overwrite behavior, but it provides meaningful context beyond 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?

The description is short, scannable, and every line adds actionable information: purpose, variants, language restriction, UI-demo exclusion, confirmation behavior, and a security warning. There is no filler or repetition of schema defaults.

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 5 parameters, a required target_dir, and no enum constraints, and the description covers the main variants and caveats. However, it leaves gaps: force behavior is not explained, target_dir expectations are not stated, and there is no mention of how the generated scaffolding interacts with the Zeus URL state beyond asking before writing. An output schema exists, so return values are less of a concern, but the missing parameter semantics prevent a higher score.

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 add meaning for parameters. It does explain app_kind values and restricts coding_language, which helps. However, it does not describe the required target_dir parameter, project_name, or force. The names are somewhat self-explanatory, but force in particular lacks semantic guidance.

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 specific verb and resource: 'Write a ZeusRuntime middle-man.' It then clarifies the supported variants (cli or api) and explicitly separates itself from UI demo tooling ('UI demos use use_sample / demo_travel_sample, not this tool'), which distinguishes it from a relevant sibling. This gives an agent a clear idea of the tool's job.

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 direct usage constraints: app_kind can be cli or api, coding_language is python-only today, and UI demos should use other tools. It also flags that confirmation may be required when no Zeus URL is stored. It does not explicitly contrast against start_project or other siblings, but the guidance is clear enough for typical selection.

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 provide idempotentHint=true and destructiveHint=false, so the safety profile is already declared. The description adds genuinely useful behavior beyond that: values are persisted ('Persisted values override MCP host ZEUS_* env defaults'), the tool explicitly excludes secrets, and presence flags only apply to credentials/LLM key. 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?

Purpose is front-loaded in the first sentence, followed by dense, purposeful guidance on secrets, URL handling, and persistence. Every sentence earns its place and there is no fluff, though six sentences make it slightly long; it could be tightened without losing 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 an 11-parameter tool with zero schema description coverage, the description covers the core flow well: secrets handling, URL-passing rules, persistence override, and presence-flag semantics. Output schema exists so return values need no explanation. But mode, role, auth_mode, and collection remain undefined, leaving meaningful gaps for such a complex, poorly-schematized tool.

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

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

Schema coverage is 0%, so the description must compensate, and it does for the most important parameters: zeus_url, bucket, scope (URL/sample passing rules) and the has_* presence flags ('Presence flags only for credentials and LLM key'). However, mode, role, auth_mode, and collection are never mentioned across 11 total parameters, leaving roughly a third of the surface unexplained.

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 specific verb+resource: 'Store non-secret prereqs for readiness' and immediately negates what it does not do ('does not store password/token values'). This distinguishes it from the secret-handling context and from siblings like readiness_check and doctor, giving an agent a precise mental model of the tool's scope.

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 exceptionally explicit when/when-not conditions: pass zeus_url/bucket/scope when the user named a URL or sample in chat, leave zeus_url empty and wait for the form otherwise, and 'Do not copy the host ZEUS_URL.' The secret-vs-env-var routing ('Put real secrets in environment variables') tells the agent what must not go through this tool. No sibling is named, but the conditional guidance is detailed enough to drive correct invocation.

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 already declare destructiveHint=true and readOnlyHint=false, so the reset behavior aligns. The description adds valuable behavioral details beyond the annotations: the zeus_url prompt when not stored, instructions to leave it empty, not to copy the host ZEUS_URL, and not to pass a password. It also discloses the gating logic and the need for force_multi to override, which an agent would not infer from annotations alone.

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 into a main purpose line followed by bullet-like sample explanations and gating rules. It is front-loaded with the core action and then provides necessary details. Each line serves a purpose, though the formatting is loose (plain text line breaks) and could be more compact or use clearer separators. Still, it is efficient and readable.

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 an output schema exists, the description does not need to explain return values. It covers the main usage context, parameter nuances, gating, and credential handling. It could mention what happens on a reset (e.g., does it overwrite existing state) more explicitly, but the destructiveHint already flags that. Overall, it is complete enough for an agent to invoke this 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?

Schema description coverage is 0%, so the description carries the full burden. It explains all three parameters: goal (default single-agent, multi-agent gated), sample (with mappings to travel, beer, api, yelp/multi and their underlying tools), and force_multi (overrides gating). It gives concrete value semantics and edge cases, fully compensating for the lack of schema descriptions.

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

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

The description states a specific verb and resource: 'Start or reset first-app coaching checklist'. It clearly differentiates from sibling tools by explicitly referencing them (use_sample, scaffold_app) and explaining how they fit into each sample path. An agent can immediately understand what this tool does and how it relates to 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 provides clear context for when to use this tool, including gating conditions (multi-agent goals restricted until single-agent smokes pass unless force_multi=true) and specific sample-derived behaviors (e.g., 'api' uses scaffold_app, 'beer' uses use_sample). It does not explicitly say 'use this instead of X' but implicitly routes to alternatives, which is adequate for these sibling 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?

Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=true. The description adds that it may ask before writing or cloning, and that no password should be passed. This is useful, but the description is fragmented and doesn't fully explain side effects or requirements like the LLM key mentioned. 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 a single block of dense, jargon-heavy text that lacks clear structure. It's not front-loaded with a clear purpose; instead, it lists technical details and internal identifiers. It could be more concise and organized with paragraphs or bullets.

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 5 optional parameters, complex behavior (cloning vs writing, travel-specific phases), and an output schema. The description is incomplete: it doesn't cover all parameters, doesn't explain return values (though output schema exists, it doesn't), and leaves many ambiguities for an agent to resolve.

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

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

Schema coverage is 0%, so the description must compensate by explaining parameters. It explains 'project_name = directory name' and 'sample=travel/beer', but it doesn't clarify 'parent_dir', 'sample_dir', or 'clone_if_missing' semantics. It omits details like when to set sample_dir vs parent_dir, and what clone_if_missing does beyond the name.

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 mentions two samples ('travel' and 'beer') and actions like 'locate/clone' and 'write catalog UI', but the phrasing is cryptic and uses jargon ('rt.agent.run_turn', 'catalog.load_for_turn merges MINI-SCHEMA') that obscures the tool's actual function. It is not a clear, plain-language statement of what the tool does, and it doesn't differentiate from siblings like 'scaffold_app' or 'start_project'.

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 some conditional hints ('travel-only phases stay on travel_golden_path', 'When no Zeus URL is stored, the MCP call asks before writing or cloning'), but it doesn't clearly state when to use this tool versus siblings. It lacks explicit when-to-use/when-not-to-use guidance and doesn't mention alternatives.

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