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

With no annotations, the description carries the burden well: it discloses the default DENY policy, the turn-blocking consequence of not responding, and the ZCODE_MCP_ALLOW_PERSIST_RULES=1 precondition for writing durable rules. It still does not explain how decisions like 'escalate' or 'modify' behave.

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?

Four short sentences, front-loaded with the core action and followed by the two facts an agent most needs (blocking behavior, deny default). No filler, though the persist_rule sentence could be tighter given it duplicates schema 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?

For a tool whose schema defines four distinct action modes (policy, list, respond), the description never mentions the action discriminator or distinguishes the modes. It covers the respond/persist path and the deny default but leaves the policy and list modes to the schema.

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

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

Schema description coverage is 100%, so the schema already documents request_id, decision, persist_rule and session_id, making 3 the baseline. The description only adds the env-var gate on persist_rule, which the schema itself already states.

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 (answer) and resource (the agent's approval, input and elicitation requests), which clearly separates it from session/chat/config siblings. It stops short of naming a sibling, but no sibling covers this domain, so the purpose is unambiguous.

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

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

Explains the operational context (the server is the runtime's only client, so unanswered requests block turns) and states the default policy is DENY, which implies urgency. However, it never explicitly says when to prefer this tool over others or when each action applies.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that creating an automation grants standing unattended authority at the creation-time mode and that at most 20 automations are retained. It still omits key behavioral context for update/delete reversibility, auth needs, action-specific effects, and scheduling semantics.

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 sentences with no wasted words. The purpose is front-loaded, followed by the two most important behavioral warnings about authority and retention.

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?

This is a complex multi-action tool with no annotations and no output schema. The description gives useful safety context for creation and a retention limit, but does not cover the action inventory, update/delete consequences, required action selection, or scheduling parameters, leaving substantial gaps 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 description coverage is reported as 100%, so the schema is the primary source for parameter meaning. The description adds no parameter-level detail, such as action semantics, cron/interval behavior, mode/model selection, or max_runs handling, so baseline 3 is appropriate.

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

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

The description states a clear resource and domain: scheduled agent runs. This distinguishes it from most zcode_* siblings, which cover status, sessions, chat, files, and settings. However, the verb 'Manage' is broad and the description never enumerates the supported actions (list, create, update, delete, check_binding).

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, when-not-to-use, or alternative-tool guidance. The description does not explain conditions for choosing this tool over related zcode_* tools, leaving usage to inference from the resource 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?

With no annotations, the description carries the full disclosure burden. It usefully explains terminal-event success semantics and degraded reporting for accepted-but-unobserved commands, but it omits the mutating or destructive effects of stop, steer, and cancel_background, as well as any auth or rate-limit behavior.

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

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

The description is three compact sentences, front-loads the core purpose, and has no filler or redundant restatement. Each sentence contributes a distinct operational point.

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 supports multiple actions (send, steer, stop, cancel_background, wait) and has no annotations or output schema. The description only covers the send/follow path and one parameter tip, leaving the other action variants and important behavioral context unexplained.

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

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

Schema description coverage is 100%, so the schema already documents most parameters. The description only repeats the tool_allowlist example already present in the schema and adds no new parameter meaning, making the baseline score appropriate.

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

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

States a specific verb and resource: submitting work to the ZCode agent and following it to a terminal state. This clearly identifies the primary chat/turn workflow, but it does not distinguish the tool from siblings such as zcode_session or zcode_status, and it omits the stop/steer/cancel variants exposed by 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 implies when to use the tool for submitting work and provides one safety-oriented usage tip for tool_allowlist. However, it does not state when to choose this tool over zcode_session, zcode_status, or other siblings, and it gives no when-not guidance.

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

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

With no annotations, the description carries the full burden and does meaningfully address it: it declares read-only behavior, notes that reads carry logEpoch and revision, and describes the staleness path (retry once, then reported degraded). This is genuine behavioral context beyond the schema. It omits auth requirements and pagination behavior, keeping it from 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?

Two compact sentences, front-loaded with the resource and its variants, followed by the read-only and staleness semantics. No filler.

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

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

For a tool with five action variants, no annotations, and no output schema, the description covers safety and staleness but never explains what each action returns or how the limit/paging parameters behave per action. The safety profile is complete; the per-action contract is not.

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

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

Schema description coverage is 100%, so the schema documents session_id and the shape of each action variant. The description only names the action labels and adds no detail on limit, before_row_id, or row_id semantics, so baseline 3 is appropriate.

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

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

States a specific verb (Read) and resource (a conversation) and enumerates the five action variants (rows, messages, events, plans, usage), which is enough to distinguish it from write-oriented siblings like zcode_chat. It stops short of explicitly naming which sibling handles what, so this lands at a strong 4 rather than a 5.

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 only usage signal is 'Read-only,' which tells the agent this is safe but not when to choose it over zcode_chat, zcode_session, or zcode_usage. There is no guidance on selecting among the five actions or on prerequisites beyond session_id.

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

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

With no annotations supplied, the description carries the full behavioral burden and does well on the highest-risk item: rewind_apply is called out as destructive and gated behind confirm:true. It also discloses the architectural constraint that checkpoints/rewind only exist for mutations made via the agent's Write/Edit tools, which is non-obvious context. It omits behavior for the attachment actions (read-only vs write, size/cost implications) and any auth/permission notes, so it is not exhaustive.

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 three capability clusters, then the constraining architecture note, then the destructive-call warning — a sensible risk-ordering. Sentences are dense but each carries information; nothing is filler, though the multi-paragraph shape makes it slightly longer than a minimal tool definition needs.

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 five-way union schema with no output schema and no annotations, the description supplies the missing safety and capability context: what mutation path produces checkpoints, and that rewind_apply is destructive. It does not describe what a 'changes' or 'rewind_preview' result contains, which is a modest gap given there is no output schema to cover it.

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

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

Schema description coverage is 100%, so the schema itself documents session_id, entity_id's extra-read cost, and the max_bytes cap; the description adds only the confirm:true requirement, which is already encoded as a const in the schema. Baseline 3 applies when the schema does the heavy lifting and the description adds little parameter-specific meaning.

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?

Opens with a concrete verb list tied to the tool's domain: 'Inspect what a turn changed, preview a rewind, and move attachments.' That maps directly onto the five action consts (changes, rewind_preview, rewind_apply, read_attachment, put_attachment), so an agent can tell it apart from zcode_session or zcode_chat. It stops short of naming how the multi-action dispatch works, but the purpose is not tautological.

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

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

Explicitly states the negative case — there is no editor document API, so 'read the file as the editor sees it' is not available — and routes file mutation to the agent's own Write/Edit tools, the only path producing checkpoints. It also flags that rewind_apply needs confirm:true. It does not, however, say when to prefer rewind_preview over rewind_apply beyond the destructive implication.

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

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

No annotations, so the description carries the full burden. It does disclose a real behavioral trait — only verified flags are emitted and unverified ones are reported as skipped, plus the model-provider prerequisite. However it omits that modes like 'build'/'edit'/'yolo' can mutate workspaces, whether the call blocks until completion, and any auth requirements beyond the provider note.

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 compact sentences with the core purpose front-loaded and no filler. Each sentence carries information, though the flag-emission note sits mid-description rather than last.

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 9-parameter tool with no output schema and near-zero schema coverage, the description leaves most calling details (mode semantics, output format, timeout, resume/continue behavior) unexplained. The flag note is helpful but insufficient for a tool of this complexity.

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 only 11% across 9 parameters, so most parameters (mode, output, target, workspace, timeout_ms, continue, action) are undocumented in both schema and description. The description adds no parameter meaning at all, failing to compensate for the coverage gap.

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

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

States a specific verb+resource: a one-shot headless run via the zcode CLI. The phrase 'requiring no protocol' differentiates it from protocol-driven siblings such as zcode_protocol and zcode_chat, so an agent can distinguish it without opening 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?

Provides one useful prerequisite ('Needs a configured model provider') and implies one-shot/non-interactive use, but never states when to prefer this over zcode_chat or zcode_protocol, nor any exclusions. Usage context is only 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?

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses that 'list' and 'status' start configured MCP servers as a side effect, that started instance ids are reported, that 'servers' avoids starting anything, and that config edits require an environment variable and a restart. These are exactly the behavioral traits an agent needs before invoking the tool.

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

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

The description is compact and front-loaded: purpose first, then the critical warning, then the safer alternative, then the config-edit requirement. Every sentence carries operational weight, and there is no filler.

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

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

For a multi-action tool with no annotations and a complex anyOf schema, the description covers the most consequential behaviors and prerequisites. It is not fully complete because it does not enumerate every action (e.g., add_server, remove_server) or clarify all action-specific parameters, but the schema supplies those constraints and the description adds the missing behavioral context.

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

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

Schema coverage is high, so the baseline is 3, but the description adds important action-specific meaning beyond the schema: it explains the side effects of 'list' and 'status', the non-starting behavior of 'servers', and the environment requirement for config edits. It does not explain the workspace, server, scope, name, or spec parameters, which leaves some semantic gaps.

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 set (Inspect and manage) and a specific resource (ZCode's MCP client surface), which is enough to distinguish it from most siblings. It does not explicitly contrast itself with zcode_settings or other zcode_* tools, so it falls short of a perfect sibling-differentiating statement.

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 and when-not-to-use guidance: 'list' and 'status' start servers, while 'servers' reads configuration without starting anything. It also states the prerequisite for config edits (ZCODE_MCP_ALLOW_MCP_CONFIG_EDIT=1 and a restart), leaving little to inference for the critical actions.

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

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

With no annotations, the description carries the full burden and mostly delivers: it discloses that catalog is filterable and NOT ranked, that select mutates state at three scopes, and critically that server scope "affects only newly spawned runtimes in this process and does not persist." That is exactly the kind of non-obvious side-effect an agent needs. It omits what the `current` action does and any auth/permission caveats for select.

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-loads the core purpose, then walks the actions in a logical order with zero filler sentences. The quoted action names and asides are stylistic but each clause carries information. Dense and slightly telegraphic, yet nothing is wasted.

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 schema defines four action branches (catalog, available, current, select) inside an anyOf, but the description only explains three — `current` is never mentioned, leaving an agent to infer it. There is no output schema, which is acceptable, but with no annotations and a complex union schema the omission of one action branch 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 100%, so the baseline is 3 and the schema already documents min_context, session_id, model, scope and provider. The description adds meaning at the action level (filterability, non-ranking, scope persistence) rather than adding per-parameter detail the schema lacks. Adequate, but it does not extend parameter meaning beyond the already-documented 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?

States a specific verb+resource pair ("Discover models and providers, and select one") and then decomposes it into named actions, so the agent knows this is the model/provider discovery-and-selection surface. It is distinguishable from siblings like zcode_settings or zcode_session by resource, though it never explicitly contrasts with them. A clean, concrete purpose that stops short of true sibling differentiation.

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

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

Explicitly routes between the two read actions: catalog is "the decision surface" while available "reports what the runtime has wired up (a different question)." It also frames catalog as deliberately unranked because "choosing a model is the job of the caller," which tells the agent what work it must do itself. It does not state prerequisites (e.g., needing a session_id for session scope) or when not to use select.

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

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

With no annotations, the description carries the full burden, and it does disclose real behavioral traits: that enabling plugins consumes the tool budget, the concrete failure mode ([1210] Invalid API parameter above roughly 89-94 tools), and the env-var gate on install/update/uninstall. However, it says nothing about reversibility, side effects on disk, or whether uninstall/reset_config destroy state — notable gaps for a mutation tool with zero annotation coverage.

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

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

Two sentences, front-loaded with purpose, and each carries information (budget constraint with a concrete error code, and the install prerequisite). The middle sentence is dense but earns its place. No filler.

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

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

For a tool with twelve action variants, no annotations, and no output schema, the description covers the operational hazards (tool-budget ceiling, install gating) but omits the action taxonomy entirely, leaving the agent to discover the capability surface from the anyOf schema. Adequate but not complete for this complexity.

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

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

Schema description coverage is 100%, so the schema documents the plugin_id and workspace fields itself. The description adds no parameter-level meaning — it never explains the twelve action variants (list, overview, describe, set_enabled, configure, reset_config, validate, install, update, uninstall, marketplace, cancel_operation) despite them being the core discriminator. Baseline 3 applies given the rich 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?

"Enumerate and manage extensions" gives a concrete verb plus resource, and the domain (plugins/extensions) is distinct from siblings like zcode_settings or zcode_mcp. It does not explicitly differentiate itself from those siblings or mention the action taxonomy, but the purpose is unambiguous. Slight terminology drift ("extensions" vs the tool name's "plugins") is a minor blemish.

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 alternatives among the many zcode_* siblings are named. The one conditional statement ("install/update/uninstall require ZCODE_MCP_ALLOW_PLUGIN_INSTALL=1") is a prerequisite rather than usage routing. An agent must infer context entirely from the schema.

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

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

With no annotations, the description carries the full burden and does so well: disabled by default, disabled outright via ZCODE_MCP_DISABLE_PROTOCOL=1, allowlist-restricted, mutating methods gated behind ZCODE_MCP_PROTOCOL_ALLOW_MUTATIONS=1, and results always flagged unreliable due to no read-back or schema guarantee. That is a rich disclosure of gating, side-effect risk, and output trustworthiness.

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 tight sentences with zero filler, and the identity ('Escape hatch') is front-loaded ahead of the enablement constraints. The information is dense but every clause earns its place; only slight compression cost keeps it off a 5.

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 gating and reliability story is complete, but the schema defines two distinct modes ('methods' to enumerate vs 'call' to invoke with method/params) and the description never explains this split or what a call returns. For a raw-protocol tool with no output schema and no annotations, that operational gap is meaningful.

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 reported at 100%, so the structured fields already document the inputs and the baseline is 3. The description adds only indirect context ('mutating methods', no schema guarantee) and does not explain the action/method/params/workspace semantics beyond what the schema encodes.

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 phrase 'Escape hatch: raw ZCode Protocol access' states a specific verb-and-resource relationship and immediately distinguishes this from the high-level zcode_* siblings (status, session, chat, etc.). An agent knows this is the unmediated low-level channel rather than another curated wrapper.

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?

Calling it an 'escape hatch' implies its when-to-use condition (raw protocol needs the curated tools don't cover) and it clarifies the prerequisites for enablement. It stops short of explicitly telling the agent to prefer the wrapping tools first, so the routing guidance is implied rather than stated.

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

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

No annotations are provided, so the description carries the full disclosure burden. It does surface one genuinely non-obvious trait: mutating actions re-read the session and fail on observed-value mismatch (compare-and-swap semantics), which is useful and not derivable from the schema. However, it says nothing about which of the 13 actions are destructive (close, compact, fork), permission requirements, or side effects of lifecycle transitions.

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 with zero filler, and the resource domain is front-loaded ahead of the transactional caveat. It is held back from a 5 only because the extreme brevity comes at the cost of hiding the action menu that defines the tool.

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

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

For a 13-action polymorphic tool with no annotations and no output schema, the description omits the single most important fact: that invocation is action-dispatched. An agent gets no read-vs-write map across the actions, no hint about the create/resume/close lifecycle ordering, and no return-value expectations, so it must reverse-engineer intent entirely from the schema.

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 reported at 100%, and the schema itself carries the load: session_id format, the first_input foreign-key warning, and the persistence default are all documented inline. The description adds no parameter meaning at all, so the baseline of 3 applies.

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 the resource domain ("ZCode session lifecycle and per-session settings") but never states a verb and never reveals that this is a polymorphic dispatcher covering 13 distinct actions (list, get, create, resume, close, fork, compact, set_model, set_mode, set_thought_level, goal, subagents, usage). Without opening the schema an agent cannot tell what it actually does. It also does not differentiate from siblings like zcode_chat, zcode_conversation, zcode_settings, or zcode_usage, whose territory overlaps with this tool's settings/usage actions.

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

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

The only usage-relevant statement is an implicit caution about mutating actions failing on value disagreement; there is no explicit when-to-use, when-not-to-use, or alternative-tool routing. For a tool whose scope overlaps zcode_chat, zcode_settings and zcode_usage, the absence of any 'use this instead of X when Y' guidance is a real gap.

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

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

With no annotations, the description carries the full behavioral load and does well: it discloses the immediate-vs-restart-required split between protocol-backed and file-backed actions, an environment-variable gate for provider mutations, and that secrets are redacted in all output. It still doesn't state that actions like remove_provider are destructive or whether mutations persist across sessions.

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 sentences, front-loaded with the core read/write purpose, then behavior, then the mutation gate. No filler and each sentence carries a distinct behavioral fact an agent needs.

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?

This is a high-complexity multiplexed tool with a dozen action variants and no output schema. The description covers the important cross-cutting behaviors but never sketches the action taxonomy (read_state, get, set_default_model, hook_trust_grant, etc.), leaving the agent to infer the full surface from the schema alone.

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

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

Schema description coverage is 100%, so the structured schema already documents parameters, making 3 the baseline. The description names set_desktop and provider mutations but adds no per-action semantics (e.g. what read_state versus get return or how workspace scoping behaves) beyond what the schema encodes.

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 pair and resource: 'Read and change configuration', and reinforces scope by naming concrete action families ('set_desktop', provider mutations). It is clear what the tool does, but it never distinguishes itself from plausible siblings like zcode_status, zcode_models, or zcode_plugins, which could also touch configuration.

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 only implied. The description gives one precondition (ZCODE_MCP_ALLOW_PROVIDER_EDIT=1 for provider mutations) but never says when to reach for this tool over zcode_status or zcode_models, and offers no exclusions or negative guidance. Enough to not mislead, not enough to route an agent confidently.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses 'Read-only; starts no turn' — a genuine trait an agent cannot get from the schema, and important since it clarifies this does not inject into the conversation. However, it says nothing about the behavior of the other five actions (e.g., what doctor diagnoses, whether sessions/runs pagination or scoping costs anything).

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 purpose and zero filler. The trailing probe note is somewhat tacked on but earns its place as the only action-level guidance.

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

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

No output schema and no annotations, so the description must carry the load — yet it documents one of six action modes and none of the return content for the others. For a multi-mode diagnostic tool, an agent cannot tell what doctor, runtimes, sessions, or runs yield or when to select them.

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 reported at 100%, so the baseline is 3. The description explains the meaning of the 'probe' action only, adding marginal value over the self-describing const values; the remaining actions (runtimes, workspace, sessions, doctor, runs) and the shared 'workspace'/'limit' fields get no explanation in either place.

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: 'Report the state of this MCP server and of ZCode itself', which is clearly a status/diagnostic tool. It does not distinguish itself from plausible siblings like zcode_usage or zcode_protocol, which also surface server/runtime information, so an agent still has to infer routing.

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 only routing guidance is that '"probe" is the diagnostic entry point', which covers one of the six action variants (runtimes, workspace, sessions, probe, doctor, runs). No when-to-use vs alternatives, no when-not-to-use, no mention of when doctor vs probe vs runtimes should be chosen.

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

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

With no annotations provided, the description carries the full behavioral burden, and 'Read-only' is the only trait disclosed. It says nothing about permissions, rate limits, scope of accounting, or what the returned metrics represent, which is thin for a zero-annotation tool.

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 short, front-loaded sentences with zero filler. The terseness is efficient but sits at the edge of under-specification.

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?

A two-parameter, no-output-schema tool still needs its parameters explained and its read-only guarantee expanded, since there are no annotations to fall back on. The description leaves both the parameter semantics and the behavioral profile largely uncovered.

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 and does not. The 'range' enum (all/7d/30d) and the fixed 'action=stats' are understandable from the schema, but the description adds no meaning about default behavior, timezone/accounting semantics of the ranges, or what the action selector implies.

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 the domain ('token and activity analytics') which tells an agent this is a usage-metrics tool, distinct from zcode_status or zcode_session. However, it gives no verb or concrete sense of what is returned (counts? breakdown by model? time series?), so the purpose is implied rather than specific.

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

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

There is no when-to-use guidance at all, nor any mention of alternatives among the many sibling analytics/status tools. An agent must guess whether this is the right tool for a given stats question.

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