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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real context the annotations don't: redaction guarantees (no password, session id, or document body echoed) and conditional behavior (Detective URL templates appear when req_id/chat_id are present).

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?

Short and front-loaded: the core purpose leads, then accepted/non-accepted inputs, then side-effect caveats. The terse 'Does not scrape Hub.' sentence is a stray fragment but the overall shape is 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?

Because an output schema exists, return values needn't be explained, and the redaction/URL-template notes are useful. But for a 16-parameter tool with zero schema coverage, leaving the majority of inputs undocumented is a real completeness gap.

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% across 16 parameters, so the description must compensate and largely doesn't. It names only about five inputs (symptom, req_id, hop name, HTTP status, result keys) and leaves chat_id, zeus_url, error_code, error_class, hop_bucket, session_id, turn_id, item_keys, node_keys, and body entirely unexplained in both schema and 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?

States a specific verb+resource: 'Map a symptom to failure_class + one generated-file change.' An agent knows the input (symptom text) and the output shape (a failure class plus a single file change). It isn't differentiated from the many siblings, but none of them are close enough to require that.

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 gives input-scoping rules ('Does not accept document bodies', 'Does not scrape Hub'), which imply usage boundaries, but never says when to reach for this tool versus doctor, readiness_check, or smoke_test_zeus. Usage is implied rather than directed.

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 establish read-only, idempotent, non-destructive, open-world behavior. The description adds genuinely new behavioral context beyond them: the data-exclusion rule ("No prompt text, document bodies, or secrets") and failure semantics ("A failed stamp sets failure_class and does not invent entity types"). These are useful disclosures the annotations do not carry.

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 purpose is front-loaded in the first sentence, but the remainder is a series of telegraphic fragments ("Entity types, display fields, text-search fields...", "fetch_chat_request stays template only.") that read like clipped notes rather than structured guidance. Every line is short, but the choppy phrasing reduces clarity and cohesion.

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, the description need not explain return values, and it covers what the summary contains, what is excluded, and how failures are signaled. For a zero-parameter introspection tool with rich annotations, that is close to sufficient, though the missing usage context leaves a small gap.

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 takes zero parameters and schema coverage is 100%, so there is nothing for the description to clarify; the baseline for a no-param tool is 4. The description's enumeration of entity types, fields, and verbs describes the output scope rather than inputs, which is not a parameter 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?

States a verb ("Summarize") and a resource ("the live chat_request stamp on public :8080"), so the basic purpose is present. However, the terminology is opaque domain jargon — "chat_request stamp", "public :8080" — with no plain-language framing of what the summary is for, and no reference to any sibling. An agent gets a rough idea but not a crisp purpose.

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 when-to-use or when-not-to-use guidance and no alternative tool named. The only indirect constraint is "fetch_chat_request stays template only", which hints at a scope boundary but does not tell the agent when this tool should be selected over its many siblings.

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

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

Annotations cover safety (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower. The description still adds real behavioral context: the password is never a parameter, the result lists loaded names and never values, and secret handling requires a chmod 600 file outside the repo — genuine security-relevant disclosure 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?

Five short sentences, front-loaded with the primary action and then the prerequisites. Dense but every sentence carries information; the telegraphic style is efficient rather than padded.

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?

An output schema exists, so return shape need not be spelled out, and the description nonetheless notes the result contains loaded names only. It covers the credential-file prerequisite, the no-argument password constraint, and the readiness_check follow-up, leaving little an agent needs missing for correct 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?

Schema coverage is 0% and the single parameter (env_file) is undocumented in the schema, so the description must compensate — and it does, specifying exactly what the file must contain (ZEUS_USERNAME, ZEUS_PASSWORD), where it should live, and its required 600 permissions. This gives the agent enough to construct a valid argument.

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 and resource: 'Load Zeus login from a mode-600 env file into this process.' It also distinguishes this from set_prereq ('stores presence flags only'), which is the closest sibling, and clarifies it does not take the password as an argument. Clear, though it does not fully map itself against the broader sibling set.

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 workflow sequencing: prepare the env file, pass its path, then call readiness_check. This tells the agent the context and downstream step. It stops short of stating when-not-to-use conditions, but the setup and follow-up guidance is concrete.

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 declare readOnlyHint/idempotentHint/destructiveHint, and the description usefully reinforces this with 'writes nothing and calls no Zeus API', plus discloses refusal behavior for invalid inputs. The enumerated return contents largely restate what the output schema already provides, so the genuinely additive context is the no-write/no-Zeus guarantee and the refusal rules.

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?

Front-loaded with the purpose and safety guarantee, then behavior and rejection rules. The return-content sentence is a long comma list that could be trimmed against the output schema, but overall there is little wasted text.

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 annotations covering the safety profile, the description only needs to add scope, refusals, and the session-id routing note — all of which it does. Minor gaps around whether the paste is written anywhere vs returned remain, but the core is 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 coverage is 0% for the single 'sample' parameter, so the description must compensate — and it does, naming valid values (beer, travel, yelp), noting a bare-yelp edge case, and stating that sample=api is rejected. This meaningfully exceeds what the bare schema string conveys.

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 operation (produce a read-only Markdown support paste) scoped to three named demo samples (beer, travel, yelp-demo). The verb+resource is clear, though it does not explicitly contrast itself against the many similarly themed siblings (use_sample, recommend_surface), leaving some differentiation to inference.

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?

Gives clear applicability (beer/travel/yelp-demo support requests) and explicit exclusions (sample=api and bare sample=yelp are refused), plus a pointer that session-id-keyed lookups belong in sample_pack_from_turn. It stops short of naming a preferred alternative tool for the refused cases.

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, openWorldHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds useful behavior: 'reset' semantics, the interactive prompt for the public :8080 URL when no Zeus URL is stored, and the gating rule — but it also instructs about a zeus_url parameter that does not exist in the schema, muddying the picture.

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 core purpose is front-loaded in one line, but it then sprawls into sample routing, alias disambiguation, gating notes, and URL guidance. The yelp/demo_yelp disambiguation is stated twice ('Not the yelp demo. Utterances yelp-demo / demo_yelp use sample=demo_yelp') and concerns are interleaved, so several sentences do not earn their 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?

An output schema exists, so return values need no explanation, and the description does cover sample routing and multi-agent gating. Gaps remain: the three schema parameters have no descriptions, and the description references zeus_url (including a password warning) that the schema does not expose, leaving an agent unclear on what it can actually pass.

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% across all 3 parameters, so the description must carry the load. It does enumerate meaningful sample values (travel, beer, demo_yelp, api, yelp/multi) and explains goal=multi and force_multi, which is genuine added meaning. It still leaves the `goal` values under-specified and references a nonexistent zeus_url field, so it only partially compensates.

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 opening sentence gives a clear verb+resource: it starts or resets a first-app coaching checklist, with the single-agent default stated. However, sibling differentiation is muddled rather than clean — use_sample is described as an internal routing mechanism here rather than a distinct tool, and the yelp/demo_yelp distinction is repeated without clearly separating this tool's purpose from the sample-selection concern.

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 real conditions (multi-agent goals gated until single-agent smokes pass unless force_multi=true, and sample routing guidance). But this is guidance for parameter selection inside the tool, not when to choose start_project over siblings like next_step, explain_scope, or scaffold_app, so routing rivals remains implied.

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 only give write/idempotent/open-world hints; the description adds substantial behavior the agent could not otherwise know — it clones repos, sets env vars (DEMO_TRAVEL_SAMPLE_DIR), writes a gitignored mode-600 config.json, requires an LLM key, asks before writing when no Zeus URL is stored, and that a 401 'stays red'. This is rich disclosure, though it is buried in prose rather than surfaced.

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?

This is a dense, unsegmented wall of ~300 words of run-on clauses with no headings, bullets, or clear front-loading; variant-specific behavior is interleaved with unrelated details (photo download paths, review doc keys, port numbers). Almost every sentence carries information, but the structure actively impedes scanning.

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 complex, open-world tool that clones and writes files, the description covers prerequisites, side effects, credential handling, and edge cases well, and an output schema exists so return values need not be explained. Remaining gaps (clone_if_missing/sample_dir behavior) are minor.

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 there are no enums, so the description must carry the load — and it largely does: it enumerates valid sample values and aliases, explains parent_dir clone behavior, and gives project_name defaults per sample. clone_if_missing and sample_dir are only obliquely covered, keeping it short of a 5.

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 opening line names the resource (UI samples) and enumerates the variants (travel, beer, catalog, demo_yelp) with aliases, but never states the core action in a single clear verb — the agent must infer 'locate/clone/write' from scattered clauses like 'write demo_beer_sample catalog UI'. Differentiation from siblings is partial (e.g. 'Extra travel-only phases stay on travel_golden_path'), so the purpose lands but only after reading the whole block.

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?

Usage is spelled out per variant (sample=travel vs beer vs catalog vs demo_yelp vs bare yelp) and it explicitly excludes misuse: 'Do not write a replacement or copy demo_beer_sample', 'Do not pass a password', 'Bare sample=yelp stays the multi-agent handoff'. It stops short of routing against named sibling tools like scaffold_app or start_project, so it isn't a full 5.

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=false, destructiveHint=false, idempotentHint=false, openWorldHint=true, so the mutation/repeat-safety profile is structured. The description adds genuine extra context: scope-session minting under basic auth, the specific checks performed, and that the result carries no secrets. It does not say what state is modified or whether reruns are safe, so it is adequate but not rich.

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 purpose is front-loaded in the first sentence, which is good. But the remaining sentences are dense internal jargon ('Pour is on', 'doc_key', 'src_keys', 'describe 200', 'a describe 200 is not this check') that costs more parsing effort than it returns, so conciseness is undermined by unreadability.

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?

An output schema exists so return value explanation is not needed, but the description must still be complete enough to call the tool correctly. It fails to document the only parameter, and against 15 siblings it only disambiguates from two, leaving an agent unclear on when this tool applies versus the surrounding suite.

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 target_dir has 0% schema description coverage and a bare empty-string default; the description never mentions it. With low coverage the description is expected to compensate, and it does not, leaving the agent to guess the format and effect of the one input.

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 specific verbs and a resource (install, start, check the catalog page) and explicitly distinguishes itself from smoke_test_zeus and smoke_test_agent. An agent can see this is a distinct catalog-page check rather than a generic smoke test. It stops short of a fully self-contained 5 because the object of the check ('list cards', 'Pour') is opaque without internal vocabulary.

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 carves out a boundary against two named siblings ('Separate from smoke_test_zeus', 'Does not call smoke_test_agent'), which is real routing guidance. However it never states the positive condition for when to run this instead of the other 12 siblings, nor prerequisites, so usage is only implied.

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