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

Annotations already declare this a safe, idempotent, closed read, and an output schema covers returns. The description adds genuine behavioral facts beyond that: it refuses placeholder values, refuses compute_local, and has a documented no-path fallback. That value is real but the delivery is opaque, and it never says what 'Extract' does on failure or how the hash is validated.

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 short sentences, front-loaded with the core action and constraint. Tightly sized, though 'ZDH-22' and 'unstamped catalog' are space that does not inform an agent.

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?

Five zero-documented parameters, four of which (mode, scope, bucket, json_text) are never mentioned, is a serious hole for a tool whose whole job is binding a contract. The output schema relieves the return-value burden, but an agent still cannot tell how to pass mode, scope, bucket, or json_text.

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 5 parameters, so the description carries the full burden and largely drops it. Only 'path' is given meaning (the empty-path fallback); mode, scope, bucket, and json_text are completely 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?

The verb+resource ('Extract stamped contract.hash') is identifiable, but the key nouns ('stamped', 'unstamped catalog', 'ZDH-22') are internal jargon an outside agent cannot resolve. It does not name any of the listed siblings, so the agent cannot place it relative to doctor, readiness_check, 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?

It does give a conditional usage rule — 'With no path, copy the hash from the live bootstrap chat_request' — and an exclusion ('Refuse placeholders / compute_local'). However, compute_local is not a listed sibling and no real alternative is named, so the routing guidance only partly helps.

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?

The annotations already establish that this is read-only, idempotent, non-destructive, and closed-world. The description adds useful behavioral context by specifying that health mode checks Python >= 3.11 and marks checklist 1.1, that .venv is handled elsewhere, and what the recommended follow-up calls are. It does not describe the return shape, but an output schema exists.

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 front-loaded with the health/doctor purpose and detail modes, then follows with operational guidance. It is reasonably sized and avoids unnecessary repetition, though the internal-tool references and next-step instructions make it slightly denser than a purely purpose-focused definition would be.

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 annotations, output schema, and single optional parameter, the description provides enough context to invoke the tool and understand its main checks. It covers the health mode, the folded env/compat/cache checks, and recommended follow-up actions. Its main gap is not clearly differentiating doctor from readiness_check or diagnose_error in the sibling toolset.

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 carry the semantic load for the single detail parameter. It lists the accepted values health, env, compat, cache, and all, and explains that env/compat/cache fold validate_env, compat_check, and semantic_cache_status. It does not fully explain the all mode or each mode's exact output, but it adds substantial meaning beyond the bare string schema.

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 identifies this as a health/doctor diagnostic tool and names the detail modes: health, env, compat, cache, and all. It specifies that the health mode checks Python 3.11+ and marks checklist 1.1, and clarifies that .venv validation belongs to verify_local_setup and website_green, which helps distinguish it from a sibling. The only weakness is that the core purpose is stated somewhat indirectly through mode descriptions rather than a single direct verb+resource sentence.

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 post-doctor guidance about calling set_prereq when a Zeus URL or sample name is already known, followed by start_project or next_step. It also warns against grepping the Zeus engine tree. However, it does not explicitly state when to use doctor versus readiness_check, diagnose_error, or website_green, nor when to choose each detail mode.

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

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

Beyond the annotations, the description discloses important behavior: no prompt text, document bodies, or secrets are exposed; fetch_chat_request remains template-only; missing_mini_schema is preserved; and a failed stamp sets failure_class rather than inventing entity types. This adds useful operational context, though it does not cover auth or rate-limit constraints.

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 front-loaded with the core purpose and the details are relevant, but it is dense with implementation-specific terms and several conditional clauses. It would benefit from clearer separation between what the tool returns and fallback behavior.

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 is parameterless, has rich annotations, and has an output schema, so the description does not need to explain return format. It still covers key edge cases around missing mini-schema headings and failed stamps. The main gap is the lack of explicit usage context relative to sibling diagnostic 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 tool has zero parameters, so parameter semantics are not a meaningful differentiator. The baseline for zero parameters is 4, and the description does not introduce any confusing parameter expectations.

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 action and resource: summarize the live chat_request stamp, including entity types, display/text-search/foreign-key fields, and verbs. It is not a tautology. However, it does not differentiate this tool from any of its siblings, and the term 'stamp' remains domain jargon rather than plain language.

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 an agent should call explain_scope versus alternatives such as doctor, readiness_check, or diagnose_error. Its conditional details are about fallback parsing behavior, not about tool selection or prerequisites.

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 idempotent/non-destructive/non-readonly, but the description adds genuinely non-obvious behavior: the result lists loaded names and never values, and set_prereq stores presence flags only. That is real security-relevant context beyond the annotations. It stops short of describing failure modes (e.g. malformed or overly permissive file).

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 action and the key precondition; every sentence carries information. The telegraphic fragments ("Then readiness_check.", "set_prereq stores presence flags only.") are slightly clipped but not 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?

With an output schema present and only one parameter, the description supplies the missing prerequisites, secret-handling contract, and follow-up step. The tangential enumeration of LLM_* variables is relevant but slightly dilutes focus; overall it is sufficient to invoke 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 coverage is 0% ("env_file: string" with no description), so the description must carry the semantics and largely does: it defines file permissions (mode-600, chmod 600), location constraints, and which keys the file may contain (ZEUS_USERNAME, ZEUS_PASSWORD, ZEUS_AUTH_MODE, LLM_*). It does not state path format (absolute vs relative) or what errors an unreadable file produces.

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 first sentence states a specific verb and resource ("Load Zeus login ... into this process") plus the required input form (a mode-600 env file). Nothing else in the sibling list does credential loading, so an agent can select it without ambiguity.

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 a concrete precondition (write ZEUS_USERNAME/ZEUS_PASSWORD outside the repo or gitignored, chmod 600, then pass that path) and a sequencing instruction ("Then readiness_check"). It also rules out an approach ("The password is not an argument"). No explicit when-not-to-use case is offered, so not a 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=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 establish that this is a read-only, idempotent, non-destructive tool. The description adds useful behavioral boundaries, notably "Does not call Zeus" and "does not write jobs.host_url," plus hints about Job-like thresholds, though the disclosure remains terse and partly opaque.

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 text is short and has no obvious padding, but it is fragmented and poorly front-loaded. The opening sentences are confusing rather than efficiently orienting the agent.

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 10 parameters, no schema descriptions, and an output schema, but the description only covers a few parameters and a couple of behavioral constraints. An agent would still lack enough information to confidently supply most inputs or understand the recommendation logic.

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 explain all 10 parameters. It only clarifies intent=nl_question and gives partial meaning for url_count, scope_count, report_wait_s, and zero-count defaults, leaving qps, page, needs_llm, settings_mode, page_interaction, and source_type_count 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?

The description never clearly states that the tool recommends a UI surface. Phrases like "Name each website input" and "One box still returns one surface" are cryptic, and the purpose must be inferred from mentions of returned inputs such as Direct list, chips, and typeahead.

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 mentions a website intent=nl_question case but gives no clear when-to-use guidance relative to alternatives. There is no explicit exclusion or routing advice involving sibling tools such as next_step, explain_scope, or website_green.

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?

Beyond the annotations (openWorldHint, idempotent, non-destructive, non-read-only) it discloses that the tool clones from GitHub, writes a mode-600 .env from .env.example while preserving existing values, sets DEMO_*_SAMPLE_DIR, downloads business photos into frontend/public, surfaces 401 as red, and refuses to run Docker. These are exactly the side effects an agent needs before invoking a write-capable setup tool, and they do 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?

A single dense block mixing sample selection, environment setup, agent-runtime internals (rt.agent.run_turn, catalog.load_for_turn, MINI-SCHEMA, max_rounds 4), and edge cases, with no paragraph breaks or front-loading. Several sentences ('No pipeline body. Do not write a job for this one-scope page.') are cryptic and only meaningful to a reader already deep in the system.

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 is present, so return values need not be explained, and many edge cases (serve choice, missing Zeus URL, catalog bucket detection) are covered. However, for a 6-parameter multi-mode tool the description still leaves sample_dir and clone_if_missing undefined and lacks a coherent overview, so an agent must assemble the contract from scattered fragments.

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 6 parameters, so the description must carry the load. It does explain the `sample` values in depth, plus `parent_dir`, `project_name` defaults, and `serve_with` (python/docker), but `sample_dir` and `clone_if_missing` are only obliquely implied, leaving two parameters materially undocumented.

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 body makes clear that this tool locates/clones demo sample checkouts and configures them, keyed by the `sample` value (travel, beer, catalog, demo_yelp), with concrete actions per mode. The opening line is a fragment ('UI sample: travel clone, beer catalog UI...') rather than a clean verb+resource statement, and it never says how it differs from sibling setup tools 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?

It gives real conditional guidance: ask the user and wait when serve_choice_required is true, pass serve_with on a later call, do not copy .env.example over a populated .env, do not write a replacement/copy demo_beer_sample, and route travel-only phases to travel_golden_path. It lacks an explicit 'use this instead of X when Y' comparison against scaffold_app/start_project, but the do/don't guidance is substantial.

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?

Adds substantial behavior beyond annotations: it mints the scope session under basic auth, returns serve_choice_required (rather than starting Python) when both a Dockerfile and compose file exist with empty serve_with, never runs Docker, and guarantees no secrets in the result. The write/side-effect nature is consistent with readOnlyHint=false. It doesn't cover error/retry behavior, keeping it below a 5.

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 core action, and the serve_choice_required sentence earns its place. But the middle section is a pile of defensive negations ("is not a search card", "is not this check", "Does not call...") that could be tightened.

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 performs multi-step orchestration, and the description covers the key decision point and failure mode plus the auth and secrets constraints. Output schema exists, so return-value explanation is not required; only target_dir semantics remain unaddressed.

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. It documents valid values for serve_with ("python or docker") and its empty-string fallback semantics, but target_dir is never described. Partial compensation warrants a 3.

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

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

States specific verbs and a resource ("Install, start, and check the catalog page") and explicitly separates itself from smoke_test_zeus and smoke_test_agent, so an agent can distinguish it from siblings. However, jargon like "Pour" and "list cards" is unexplained, leaving the exact scope somewhat opaque.

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 explicit exclusions ("A describe 200 is not this check", "Does not call smoke_test_agent") that route the agent away from wrong tools, plus the concrete condition that triggers serve_choice_required. It stops short of a positive "use this when X" statement, but the exclusions carry strong guidance.

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