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

With no annotations, the description carries the full behavioral burden, and it does disclose a genuinely important trait: out-of-scope agents return NOT_FOUND, indistinguishable from a missing id. That prevents an agent from misreading a permission failure as non-existence. It does not state read-only status or return shape, but the output schema covers the latter.

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 sentences with zero filler; the core action leads and the surprising scoping caveat follows. Every clause earns its 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?

For a one-parameter read tool with an output schema, the description covers the one non-obvious failure mode an agent must know. Return values are handled by the output schema, so nothing critical is missing, though read-only confirmation is absent.

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

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

The single agent_id parameter is fully documented in the schema (100% coverage, including 'REQUIRED'), so the baseline is 3. The description adds no format, naming, or resolution semantics beyond what the schema already provides.

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 ('Return one agent's details') and names a key returned field (last_seen_at), which is crisper than the bare name. It never explicitly contrasts with agent_list or agent_whoami, so sibling differentiation is only implied.

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 statement of when to call this rather than agent_list, agent_whoami, or agent_register. The only qualifying information is a behavioral scoping caveat, not usage 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 well: it discloses a caller-dependent visibility rule (authenticated callers see only agents within their comm scope plus themselves; anonymous callers see all). It omits pagination/ordering behavior, but the output schema exists to cover the return shape.

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 no filler; the scope ('global') and the visibility rule are front-loaded rather than buried. Every clause carries information the caller 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 parameterless list tool with an output schema and no annotations, the description supplies the one thing structured data cannot: who sees which agents. Only pagination/results-size behavior is left unstated, a minor gap given the schema covers the return shape.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate. Baseline 4 applies for a zero-parameter tool.

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 ('List registered agents'), names the scope ('global'), and previews the returned fields (role/capabilities, last_seen_at). It does not explicitly distinguish itself from agent_get or agent_whoami, but 'List ... (global)' implies enumeration vs single-record retrieval.

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 never says when to reach for this tool versus agent_get, agent_whoami, or agent_register, nor does it state any preconditions for calling it. Usage context is only weakly implied by the word 'List'.

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 burden and does meaningful work: it discloses the authorization model (self-only, PERMISSION_DENIED on violation) and the fail-closed capability policy against the central catalog. It omits whether unspecified fields are preserved or cleared, and whether updates are idempotent.

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?

Compact and front-loaded: the action, the self-only restriction, and the capability constraint each appear in their own short clause, with the doc link last. No filler, though the clipped style borders on telegraphic.

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 not be explained. However, the description leaves two real gaps for a mutation tool: whether this creates an agent that doesn't yet exist (the name implies registration) and why a required agent_id is needed if the operation is strictly self-only. For a write tool with no annotations, these should be resolved.

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% and the schema already explains role matching, the global agent_id, free-form metadata, and the three capability input shapes with the fail-closed rule. The description restates the field list and the catalog constraint without adding syntax or format detail beyond the schema, so the baseline 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?

States a specific verb and resource: update the caller's own agent profile, with the affected fields (role/capabilities/metadata) enumerated. It is clearly distinguishable from read-oriented siblings like agent_get, agent_list, and agent_whoami. The tool name 'agent_register' suggests creation rather than update, which slightly muddies the read of the purpose, but the prose is unambiguous about the action.

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 an explicit precondition (SELF-ONLY, otherwise PERMISSION_DENIED) and routes capability discovery to capability_list. It does not, however, state when an agent should call this versus agent_whoami (read) or when a first-time registration versus a subsequent edit 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?

With no annotations, the description carries the burden and does disclose the return surface (agent_id, role, capabilities, metadata, permissions, effective_policies + governance) and notes communication style is conditional ('when set'). It stops short of stating auth requirements or that the call is strictly non-mutating, but the self-read framing makes that clear.

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 front-loaded sentence plus a docs pointer; no waste. The field list is dense but each item earns its place by telling the agent what it will receive.

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 parameterless self-profile read backed by an output schema and a docs link, this is essentially complete. The only soft gap is the absent explicit contrast with agent_get/agent_list.

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?

Zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The enumerated fields are extra value, though the output schema already documents returns.

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 ('Return') and a precisely scoped resource ('YOUR OWN profile'), and enumerates the fields returned. The 'YOUR OWN' framing cleanly distinguishes it from sibling agent_get/agent_list, which fetch other agents' records.

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 implied by the self-scoped wording rather than stated. It never explicitly says to use agent_get for other agents or when this is preferable, so the agent must infer the routing from the sibling 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 behavioral burden, and it discloses a genuinely important trait: reads are audience-scoped and an outside caller receives NOT_FOUND that is deliberately indistinguishable from a missing id. That is valuable context an agent cannot infer from the schema. It does not state permission/auth requirements or whether the operation is read-only in a broader sense, so it falls short of 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 tightly written sentences with the retrieval scope front-loaded and the security caveat second. Every clause earns its place 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?

An output schema exists, so return-value explanation is unnecessary, and the description covers the non-obvious audience-scoping behavior. For a two-parameter read tool this is nearly complete; only auth/permission expectations remain unstated.

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 both parameters are already documented, and the description largely restates the project_root-to-workspace relationship already captured in the schema. It adds no format, validation, or edge-case detail beyond the structured fields.

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?

Names a specific verb (Retrieve) and resource (artifact by id) plus the scoping mechanism (workspace resolved from project_root). It is clearly distinguishable from the sibling artifact_put, which performs the inverse operation.

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 implied by 'Retrieve an artifact by id' but there is no explicit when-to-use statement, no exclusions, and no pointer to alternatives (e.g., artifact_put for writes, or a listing tool). The audience-scoping sentence hints at a failure mode but does not guide tool 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?

No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about overwrite/duplicate behavior, idempotency, required permissions, size limits, or failure modes. 'Resolved workspace' hints at a dependency on workspace_resolve but does not explain it.

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 a useful docs pointer and no filler. Slightly terse for a write operation, but 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?

This is a mutation tool with no annotations and no output schema referenced in the description, so ambiguity about what a successful registration returns or does to existing artifacts is significant. The schema covers inputs and the docs link covers unspecified detail, but the description itself leaves the agent without the behavioral context needed to call it safely.

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 all six parameters (including the path-or-content exclusivity rule and the artifact_type enum-in-prose) are already documented in the schema. The description adds no parameter meaning beyond what is structured, so the baseline of 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 ('Register') and resource ('artifact') plus the accepted artifact types and the workspace scope. It is clearly distinguishable from artifact_get by direction, though it doesn't explicitly name that sibling as the converse operation.

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 guidance on when to use this tool versus alternatives such as shared_md_render or artifact_get, and no prerequisites or exclusions. The only pointer is an external docs URI, which an agent cannot resolve inline.

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 supplied, so the description carries the full behavioral burden. It does disclose some useful behavior – unowned capabilities appear with agent_count 0, and agents are filtered to the caller's 'comm reach' – but says nothing about read-only nature, pagination, or what 'Normalised as capability routing matches' implies for the results.

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

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

The purpose is front-loaded, which is good, but the remainder is a colon-glued run-on with parentheticals and a dangling fragment ('Normalised as capability routing matches.') that obscures meaning rather than saving space. It is dense without being clear.

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 no parameters, the description only needs to frame the tool, which it does: it names the catalog, the owner merge, and the agent_count-0 edge case. The unexplained 'comm reach' and 'routing matches' phrasing are the only real gaps for such a low-complexity 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?

The schema declares zero parameters at 100% description coverage, so there is nothing for the description to compensate for. Baseline 4 applies for a parameterless list tool.

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 ('List the capability catalog') and clarifies that it merges owner/agent information, so the agent can tell what data comes back. However, the purpose is diluted by undefined terms like 'comm reach' and 'capability routing matches', and it does not differentiate itself from adjacent listing tools such as agent_list or tag_list.

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 indication of when to use this tool versus alternatives like agent_list, agent_get, or tag_list, nor any stated preconditions or exclusions. Usage must be inferred purely from the word 'List'.

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 burden. It usefully discloses idempotency, the created=false outcome, and that channels are organizational labels rather than ACLs — a genuinely non-obvious semantic. However, it says nothing about permissions, workspace-scoping errors, or failure behavior, so meaningful gaps remain.

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 sentences, front-loaded with the action and the idempotency caveat. Every clause earns its place with 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?

An output schema exists, so return values need no explanation, and both params are fully described. The description covers semantics and idempotency; only authorization/prerequisite context is absent, which is minor for a low-risk creation 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 description coverage is 100% and the schema already documents both name (max 64 chars, unique per workspace, idempotent) and project_root. The description only restates the idempotency aspect, adding no syntax or format detail beyond the schema; baseline 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?

States a specific verb (Create) and resource (channel) with scope (by name) and an idempotency qualifier. An agent can distinguish this from channel_list and other channel siblings 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?

Clear context for when to call it — creating a channel by name, tolerating repeats via idempotency. It does not name alternatives (e.g. channel_list) or state exclusions, but the usage window is unambiguous.

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 discloses one useful trait (a default 'general' channel is seeded), which implies a read-only listing, but says nothing about ordering, pagination, archived/hidden channels, or whether it reflects workspace scope. For a zero-annotation tool this leaves significant gaps.

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 front-loaded sentence with no wasted words. The scoping detail is embedded compactly in the parenthetical.

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 structure need not be explained, and the single required parameter is fully described in the schema. The description covers the default-seed behavior but omits ordering and whether non-default channels are included, which is minor for a simple list 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 description coverage is 100% and project_root is fully documented as the workspace scope in the schema itself. The description adds no further meaning about the parameter, so the baseline 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?

States a specific verb and resource: 'Return the workspace channels'. An agent can distinguish it from channel_create by the listing verb, but the description never explicitly contrasts it with the sibling create tool. Clear purpose with no explicit 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?

There is no guidance on when to call this versus channel_create or how the result should be used. The parenthetical about 'general' being seeded is context, not a usage condition. The agent must infer the use case entirely.

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 key traits: the output is an aggregated ok|warn status over 7 metric blocks with thresholds, and the call requires the feature_health feature and health.read permission. It stops short of explicitly stating it is read-only/no-side-effect, which an agent could still want confirmed.

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: the first front-loads what the tool produces and its scope, the second states the hard requirement. Nothing repeats the schema or annotations.

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 an output schema exists, the description needn't enumerate return fields, and it already summarizes the return shape and permission prerequisites. The main remaining gap is the absence of usage context that would tell an agent when to reach for this versus other observability-style read 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?

Schema description coverage is 100%, so the window enum values, agent_id purpose, and project_root scope are already fully documented in the schema. The description only echoes 'windowed' without adding syntax, format, or default guidance beyond what the schema provides. Baseline 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?

Names a specific resource (coordination-health) and scope (workspace, windowed) plus the concrete output shape (aggregated ok|warn status, 7 metric blocks). No sibling tool overlaps this domain, so differentiation isn't a concern, but it stops just short of the model 5 by describing a report rather than an explicit action.

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?

No when-to-use or when-not-to-use guidance is given. The only conditional information is a prerequisite (requires feature_health and health.read), which is an auth/permission note rather than usage direction. An agent must infer from the name that this is a health-check tool to call proactively.

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 behavioral burden well: it discloses the O(1)/no-scan cost profile, the anchor/monotonic semantics (only events after now), and the sentinel return (0 for empty). It never states read-only or auth/permission needs, but for a pure cursor read this is a solid disclosure.

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?

One dense sentence with the anchor semantics front-loaded and cost/return details in tight parentheses. Every clause earns its place (O(1), no scan, append-after-now scoping, empty sentinel).

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

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

With an output schema present, the return shape need not be explained, and params are fully covered by the schema. The description supplies cost and usage framing, giving an agent enough to call it; only explicit sibling routing is missing.

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 stream, agent_id, and project_root are already fully documented in the schema (including scope and enum-ish stream values). The description adds no parameter-level meaning beyond what the schema provides, so the baseline 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?

States a specific verb and resource ("Return the stream's CURRENT END as a cursor") and adds the operational role ("pre-flight monitor anchor"). It implicitly separates this from event_get/event_wait by framing it as an anchor rather than a reader, but never names a sibling explicitly.

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?

"Pre-flight monitor anchor so you see only events appended after now" gives a clear when-to-use context: grab this before monitoring so subsequent reads are scoped to new events. No explicit when-not or named alternatives (e.g. event_get vs event_wait) are given, so it stops short of 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?

With no annotations, the description carries the full burden and does well: it discloses non-blocking behavior, the visibility/comm-scope filtering rule, and cursor pagination. It omits auth/prerequisite requirements and any rate-limit or error behavior, keeping it short of 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 tight sentences plus a docs pointer; the core purpose and the most surprising behavior (non-blocking, scope filtering) are front-loaded with zero 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?

An output schema exists, so return values need not be explained, and the description covers pagination, blocking behavior, and visibility. What remains thin is guidance on choosing among the many sibling event/inbox readers, but nothing required to invoke the tool is missing.

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 all 7 parameters including cursor, limit, stream, and filters. The description adds only the high-level 'cursor-paginated page' framing, not parameter-specific semantics beyond the schema, so baseline 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?

States a specific verb (Read) and resource (a page of the event log) plus a distinguishing behavioral trait: non-blocking. It implicitly separates itself from event_wait, but it never names that sibling or event_cursor explicitly, so sibling differentiation is left 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?

The '(non-blocking)' tag implies you use this when you don't want to wait, but no when-to-use/when-not statement or explicit alternative is given. The visibility rule ('actors outside your comm scope are omitted; yours and system events always show') is useful context but is about results, not tool 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?

With no annotations, the description carries the full burden and does a solid job: it discloses the visibility scoping ("actors outside your comm scope omitted"), the blocking semantics of the timeout, and points to a monitoring reference. It stops short of permissions or rate-limit context, but the key behavioral traits of a long-poll read are surfaced.

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

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

Three tight sentences, front-loaded with the primary action and the blocking rule, with no filler. Slightly dense but every clause earns its 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?

For an 8-parameter read tool with an output schema and full schema coverage, the description supplies the missing behavioral context (scoping, blocking, monitoring reference) without needing to explain return values. Adequate for correct invocation.

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

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

Schema coverage is 100%, so all eight parameters are already documented, including the 0/omitted/null snapshot semantics for timeout and the limit/cursor meaning. The description merely restates the timeout rule rather than adding new syntax or format detail, so the baseline 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?

States a specific verb and resource ("Read the event log") and disambiguates itself from the sibling event_get by noting the scoping relationship and by being the tool that offers long-polling. An agent can tell what it does, though the distinction from event_get/event_cursor is left implicit.

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 blocking-vs-snapshot behavior is explained, which implies when you'd reach for this tool, but there is no explicit statement of when to prefer it over event_get (plain read) or event_cursor, and no exclusions or prerequisites are given.

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 burden and does well: it discloses the creator-only authorization requirement, the state precondition (OPEN only), and that strict-mode trust requires passing session creds. It omits failure behavior and whether cancellation is reversible, 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?

Extremely front-loaded and dense: state transition, purpose, precondition, and auth note in three short clauses. The telegraphic style is efficient, though the clipped phrasing slightly risks ambiguity.

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?

Output schema exists so return values need no explanation. For a mutating, auth-sensitive tool the description covers the state constraint, authorization model, and strict-mode requirement adequately, leaving only edge-case failure behavior unstated.

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 agent_id, handoff_id, session_id, and session_secret in detail. The description reinforces the creator constraint and strict-mode credential requirement, but adds little syntax or format detail beyond the schema, matching the baseline 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 a specific verb and resource with an explicit state transition ('OPEN -> CANCELLED') and a concrete purpose ('retract a handoff nobody should take'). An agent can distinguish it from handoff_reject and handoff_complete from the description alone.

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 when-to-use context with a concrete example ('a pool target matching zero agents') and a precondition ('Only OPEN handoffs cancel'). It does not explicitly name the alternative tools (reject/complete) or when NOT to cancel, so it stops short of 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?

With no annotations, the description carries the full burden and does well: it discloses atomicity, the single-winner outcome, the structured error for losers, the auth requirement in strict mode, and the returned fields (payload + claimed_by/lease_expires_at), which implies a lease/ownership model. It stops short of stating lease duration, renewal expectations, or whether a claim can be released, which would matter for a state-mutating coordination primitive.

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 tight sentences, front-loaded with the core behavior, then the return contract, then the conditional auth note. No filler and nothing buried.

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

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

An output schema exists, so return-value detail need not be expanded, and the description correctly covers concurrency semantics, auth modes, and failure shape. What's missing is post-claim lifecycle context (what the lease implies, and that handoff_complete/reject/cancel are the follow-up actions), which would help an agent plan the next step.

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 all five parameters are already documented in the schema. The description's mention of session_id + session_secret in strict mode restates what the schema descriptions already say, adding no new parameter semantics. Baseline 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?

States a specific verb (claim), resource (handoff), and precondition (OPEN), plus the key semantic property (atomic, single winner). An agent can immediately distinguish it from handoff_create, handoff_list_available, handoff_get, and handoff_complete.

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 conditional guidance for trust_mode=strict (pass session_id + session_secret), which tells the agent when extra credentials are needed. It does not, however, contrast itself against adjacent siblings like handoff_get or handoff_verify, so the when-not guidance is incomplete.

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. It discloses the ownership restriction and the strict-mode session-credential requirement, which is valuable. However, it omits irreversibility, error behavior, and the side effect that the result is persisted and delivered to the creator inbox (that detail only lives in the schema).

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 sentence that front-loads the key state-transition and ownership facts with no wasted words. The terse arrow notation is efficient, though slightly cryptic for an agent parsing on first read.

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 state-mutating handoff tool with an output schema covering returns, the description supplies ownership, transition logic, the verify path, and auth mode. That is nearly sufficient, with only irreversibility/error semantics left 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 description coverage is 100%, so the schema already documents agent_id, handoff_id, session_id/secret, result, and project_root. The description adds the strict-mode credential hint but otherwise repeats what the schema provides. 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+resource ('delivery of a CLAIMED handoff') and spells out the resulting state transitions (-> COMPLETED, or -> VERIFYING). It is clearly distinguishable from siblings like handoff_verify, handoff_reject, and handoff_cancel.

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 branching condition for COMPLETED vs VERIFYING and names handoff_verify as the decider when acceptance_criteria were set, plus the owner-only constraint. It stops short of explicitly stating when to prefer handoff_cancel or handoff_reject instead, so no full when-not coverage.

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 discloses that target/visibility are validated, that a 'handoff.created' event is emitted, and that status/result should be polled via handoff_get. However, it omits permissions, error handling, or side effects like ownership transfer, leaving significant gaps.

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 tightly written sentences: front-loaded action, validation, event, next step, and a documentation link. Every sentence earns its place with no redundancy.

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 10 parameters, no annotations, and an output schema that covers return values, the description is partially complete: it names the creation, validation, event emission, and follow-up poll. But it omits failure modes, required permissions, and other behavioral traits needed for a complex coordination tool, relying heavily on the external doc link.

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 all 10 parameters thoroughly. The description only reiterates that target/visibility are validated and adds no parameter syntax or meaning beyond the schema, making the baseline 3 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 specific verb ('Create') and resource ('handoff') with additional state ('OPEN') and validation scope ('validates target/visibility'). It clearly identifies the operation, though it does not explicitly differentiate from siblings like handoff_claim beyond the verb 'Create'.

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 implies when to use by stating the next step ('After creating, poll handoff_get for status/result'), but gives no explicit when-not conditions or alternative selection guidance relative to other handoff tools (claim, complete, etc.). Usage is only implied.

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

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

No annotations are provided, so the description bears the burden. It signals this is a read and notes conditional fields ("if set"), but says nothing about the visibility gating described in the schema, permissions, or auth requirements. An output schema exists, so return-format explanation is not needed.

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 that front-load the verb and resource, with the field list and doc pointer kept short. The trailing documentation link is mildly expendable but harmless.

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

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

For a simple read tool with a full output schema and complete parameter coverage, the description covers purpose and return fields adequately. The only real gap is the absence of any behavioral note on visibility/access, which the schema partially covers.

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% and all three parameters are documented there, so the baseline is 3. The description adds no syntax or format detail beyond restating that the read is by id.

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 ("Read a handoff by id") and enumerates the fields returned (status, claimant, payload, result/rejected_reason), which distinguishes it from list-oriented siblings like handoff_list_available. It doesn't explicitly name the sibling it contrasts with, so it falls short of 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 creator's path to the outcome" hints at context of use, but there is no explicit when-to-use guidance, no when-not, and no named alternatives (e.g. handoff_list_available for discovery). Usage is only implied.

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

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

With no annotations, the description carries the burden and does disclose the non-obvious side effect (expiring leases before listing) plus the 'metadata-only until claimed' constraint, which an agent would not infer from the name. It omits permission/auth requirements and any note on whether lease expiration is destructive or affects other callers.

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 sentence, front-loaded with the side effect and the action, with no filler. The semicolon clause packs scope, pagination, and the metadata-only caveat efficiently, though it is a lot compressed into one sentence.

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

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

An output schema exists, so return shape need not be explained. The description covers the key behavioral facts (lease expiration, eligibility scoping, pagination, metadata-only pre-claim state) needed to call it correctly; only auth/permission expectations are 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 100%, so limit/cursor/agent_id/project_root/timeout_seconds are already fully documented; the description only reinforces 'paginated' and caller-scoped visibility. Baseline 3 is appropriate since the schema does the heavy lifting.

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 (list) and resource (OPEN handoffs) plus a scope qualifier ('visible+eligible to the caller'), which separates it from handoff_get/handoff_claim. It also names a side effect ('Expire leases'), but does not explicitly contrast with sibling list/claim tools.

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 implied by 'visible+eligible to the caller' and the paginated metadata-only framing, but there is no explicit when-to-use versus handoff_get or handoff_claim, and no stated preconditions. The long-poll semantics are left to 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 burden, and it does disclose the auth requirement in trust_mode=strict. It does not cover reversibility, idempotency, error conditions, or what happens to the counterparty beyond what the schema's reason field already says.

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 core action and state transitions, then the auth caveat. No wasted words.

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 mutation tool with a full output schema, the description covers purpose, state transitions, and auth preconditions adequately. Remaining gaps (reversibility, side effects) are minor given the rich schema and output 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 every parameter is already documented in the schema, including the trust_mode conditional on session_id/session_secret. The description merely restates that auth rule, adding no meaning beyond the structured fields.

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 (reject) plus the resource (handoff) and even enumerates the exact state transitions it performs (CLAIMED->REJECTED, OPEN->REJECTED). This cleanly distinguishes it from siblings like handoff_cancel, handoff_complete, and handoff_verify.

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 state transitions imply when the tool applies, and the second sentence gives an auth precondition for strict mode. However, there is no explicit guidance on when to reject versus cancel/complete a handoff, nor any stated exclusions.

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

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

With no annotations, the description carries the full burden, and it does disclose the two verdict outcomes, that feedback overwrites previous feedback and goes to the claimant's inbox, and the strict-mode credential requirement. It omits error/edge behavior (wrong state, idempotency, concurrency) that matters for a state-mutating 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?

It is short and front-loads the core behavior, but the telegraphic style ('pass session creds', arrow notation) sacrifices readability, and the opening clause is dense enough that an agent must re-read it to parse the state transitions.

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 not be explained, and the description covers the primary path. For a 7-parameter, multi-mode (open vs strict trust) verification tool with no annotations, however, more operational context (preconditions, failure behavior) would be needed for full completeness.

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 100%, so the schema already documents every parameter including feedback and the session credentials. The description's only added param meaning is a restatement of the strict-mode session requirement ('pass session creds'), which the schema already states, so baseline 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 a specific verb and resource ('verifier-only verdict on a VERIFYING handoff') and spells out both state-machine outcomes, which lets an agent distinguish it from handoff_complete, handoff_reject, and handoff_cancel. It is clear but relies on terse jargon rather than plainly naming the siblings it is not.

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?

'Verifier-only' and the VERIFYING precondition imply when the tool applies, and the agent_id note ('the claimant is always refused') narrows the caller. But it never explicitly contrasts this with the sibling verify/complete/reject tools or states what to do when the handoff is in another state, so usage is only implied.

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

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

With no annotations, the description carries the burden and does disclose two real traits: it emits a message.read receipt to each sender (a visible side effect) and returns a specific result shape. It stops short of permissions, rate limits, or what happens to unacknowledged messages.

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, no filler, purpose and return shape and side effect front-loaded in that order. Every sentence earns its 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 not be spelled out, yet the description still names the response keys. Auth and idempotency are covered by a rich schema. The main gap is the absence of when-to-use routing among the inbox_* siblings.

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 agent_id, session_id, message_ids and session_secret are fully documented in the schema, including idempotency and trust-mode requirements. The description adds nothing about parameters, so baseline 3 is correct.

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: acknowledge messages into history, with a parenthetical clarifying it counts as a read. This is clear enough to distinguish it from inbox_pull/inbox_peek, but it never names those siblings or explains how ack differs from them.

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?

No guidance on when to acknowledge versus pulling, peeking, or reading history. The idempotency note lives in the schema, not the description, and there is no mention of prerequisites or when-not-to-use.

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 and does well: it declares the operation read-only, characterizes cost ('cheap'), and discloses non-obvious counting semantics (expired in-flight leases count as unread; parked excluded). It doesn't cover auth requirements or rate limits, but for a read-only counter this is solid disclosure.

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, zero filler, with the return shape front-loaded and the usage rule and edge-case semantics trailing. Every clause earns its 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?

Output schema exists, so return values need not be re-explained; the description supplies the selection context and the subtle counting rules an agent needs to interpret the numbers correctly. Complete for a single-param read 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 100% and the single agent_id parameter is fully documented in the schema (global inbox, reaches you in any workspace, REQUIRED). The description adds nothing about the parameter, so the baseline 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?

States a specific verb (Return) and resource (inbox lane sizes) and enumerates the exact returned fields {unread, in_flight, read}. An agent can distinguish this counting tool from inbox_pull/inbox_peek/inbox_history without opening any 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?

Gives explicit usage context ('Cheap READ-ONLY between-turns check') and a routing rule ('pull when unread > 0') that points to the sibling inbox_pull. No when-not-to-use guidance is given, but the positive selection rule is clear.

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 behavioral burden and discloses the key atomicity trait: all-or-nothing, with per-message failure and no extensions if any id is not in-flight. It also clarifies the lease is extended from now. It does not discuss authentication or return values, but the output schema handles returns and the input schema documents session/trust requirements.

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 focused sentences with no filler. The core action is front-loaded, followed by the critical failure condition. Every sentence earns its 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?

Given a 5-parameter mutation-like tool with 100% schema coverage, an output schema, and no annotations, the description covers the essential behavior: lease renewal and all-or-nothing failure. It does not mention trust-mode auth requirements, but those are fully documented in the schema, so the description is largely complete 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 100%, so the schema already explains all parameters, including extend_seconds clamping and session trust modes. The description adds only mild context via '(now + extend_seconds)' and the all-must-be-in-flight constraint, which is also in the schema. 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 specific verb and resource: renew the lease on in-flight messages. It also distinguishes this from ack/finish behavior by specifying messages 'you pulled but have not finished.' An agent can clearly identify the operation 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?

The description gives clear context for use: messages that are in-flight but not yet finished need their lease renewed. It does not explicitly name alternatives like inbox_ack or state when not to use this tool, so it falls short of full when/when-not guidance, but the implied usage is clear.

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 burden: it declares READ-ONLY, states the sort order, and discloses a non-obvious behavioral guarantee (keyset pagination keeps pages stable even while new messages are acknowledged). It stops short of covering auth/permission requirements or rate limits.

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 sentence; the operation and its scope come first, and the read-only declaration is a clean trailing flag. 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?

An output schema exists, so return values need not be explained, and all four parameters are documented at 100%. The remaining gap is minor: no note on auth/permission expectations for reading the global inbox, but the essentials for correct invocation are present.

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 limit, cursor, profile and agent_id in detail. The description adds only the conceptual meaning of the cursor (keyset pagination), which is useful framing but not parameter-level detail beyond the 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 gives a specific verb (List), resource (acknowledged/read messages), ordering (newest-first) and pagination model. It implicitly separates itself from siblings like inbox_peek by scoping to already-acknowledged messages, but it never names an alternative tool explicitly.

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 implied (you call this to review what you've already acknowledged), and the parenthetical about stable pages while acknowledging hints at a concurrent-workflow use case. However there is no explicit when-to-use/when-not-to-use guidance or reference to a sibling alternative.

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 well: it declares READ-ONLY, states the default payload (body_preview + body_bytes), and flags which behaviors require explicit opt-in. It stops short of describing ordering, pagination, or what 'in-flight' concretely means for a caller.

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 dense clauses with zero filler; the non-consuming read-only framing is front-loaded before the default and opt-in details.

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 covers the read-only posture, defaults, and opt-ins. It is nearly complete, missing only hints about result ordering/volume expectations.

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 100%, so the schema already documents limit, profile, agent_id, include_bodies and include_parked in detail. The description only restates the include_parked/include_bodies opt-in defaults, adding little beyond the structured fields — the 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 ('triage/peek') and resource ('pending messages: unread + in-flight') and immediately scopes it as non-consuming, which cleanly separates it from the sibling inbox_pull. An agent can pick this over inbox_pull without opening either 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?

Gives clear context for when to use it (triage without consuming, envelope-only by default) and notes the opt-in flags for deeper inspection. It never names inbox_pull as the consuming alternative in the description itself, so the when-not 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, the description carries the full burden and does disclose the key trait: at-least-once delivery with unacked pulls being redelivered, plus the fact that bodies are returned. It omits auth/trust-mode behavior and what happens on ack, but the redelivery contract is the critical disclosure and it is 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?

Three short clauses with no waste; the core semantics and the at-least-once caveat are front-loaded, and the docs pointer is a compact trailing reference instead of prose bloat.

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 6 params covered at 100%, an output schema present, and the delivery guarantee stated, an agent has what it needs to call this correctly. Only the trust-mode/auth nuance and how the returned messages differ from inbox_peek output are left unstated.

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 100%, so limit, profile, lease_seconds, session_id, and session_secret are already fully documented in the schema. The description adds no parameter-level detail beyond implying the lease/renew flow, 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?

States a specific verb and resource ('take your unread messages into in-flight and return them WITH body') and adds a differentiating qualifier ('index-free; no cursor') that separates it from cursor-based readers like event_cursor. It does not name the closest sibling (inbox_peek), so it stops short of 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 description implies the use case (consume unread mail as in-flight messages) and points to inbox_extend for mid-turn lease renewal, but never states when to prefer this over inbox_peek, inbox_history, or message_list. Usage is inferred rather than guided.

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 well on side effects: it discloses persistence, fan-out to recipient inboxes, emission of a message.created event, and that the response confirms delivery with recipients + delivered_count. It omits auth/trust-mode requirements and any failure/partial-delivery semantics, so it falls short of 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?

Three tight clauses: the core action and side effect are front-loaded, the response contract follows, and the docs pointer is last. Every sentence earns its place with zero 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?

An output schema exists so return values needn't be explained, and the schema richly covers routing, session, and artifact semantics. For an 11-parameter tool the description is somewhat thin on auth/trust-mode context, but the docs reference plus the schema make it usable end-to-end.

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 all 11 parameters, including the complex target routing grammar. The description adds no parameter-level meaning beyond what the schema provides, which is the baseline 3 for full-coverage schemas.

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 specific verbs and a resource ('persist a message and fan it out to recipient inboxes; emit message.created'), so an agent immediately knows this is the write/send path. It does not explicitly name read siblings (message_get, message_list, message_wait) to differentiate, which keeps it short of 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?

There is no when-to-use, when-not-to-use, or alternative-tool guidance. The description explains the mechanics of sending but never states the conditions under which an agent should call message_create rather than inbox_pull, message_status, or channel tools; it only points to external docs.

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: it discloses that the tool always fails, the exact error code, and that the response contains the replacement call. That is complete transparency for a tombstone 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?

A single, front-loaded sentence stating the migration, the replacements, and the return behavior. Every clause earns its place with no waste.

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?

Although an output schema exists, the description already explains the only meaningful return behavior (ok:false code=MIGRATED with the replacement call). For a zero-parameter migrated stub, this is 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?

There are zero parameters, so the baseline is 4. The schema has 100% coverage and the description correctly implies no input is needed, though there is no additional parameter meaning to add.

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 precisely what the tool now is: a migrated stub that always returns ok:false with code=MIGRATED. It names the three replacement tools (inbox_pull / inbox_peek / inbox_history), so an agent can immediately distinguish it from those siblings.

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

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

It explicitly tells the agent not to use this tool and to use the replacements instead, with the condition that any call will return a MIGRATED error. No inference is required about when or whether to call message_get.

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 meets it: it discloses the exact return contract ('Always returns ok:false code=MIGRATED'), so an agent knows the call is a guaranteed no-op failure and can avoid it entirely.

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 front-loaded sentence beginning with 'MIGRATED' conveys status, replacements, and exact behavior with zero filler. Every clause earns its 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?

For a deprecated stub, the description covers everything an agent needs: deprecation status, replacement routing, and the deterministic failure response. An output schema exists, but the description still correctly summarizes the return contract rather than leaving the agent to discover 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?

The tool takes zero parameters and the schema is empty at 100% coverage, so there is nothing for the description to clarify. Baseline 4 applies; no parameter discussion is needed or given.

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 exactly what this tool now is: a migrated tombstone that always returns ok:false code=MIGRATED. It names the sibling replacements (inbox_peek, inbox_history, event_get) so an agent can immediately tell this tool apart from them without inspecting any 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?

Explicit routing: it says the tool is replaced and maps each use case to its correct alternative — inbox_peek/inbox_history for 'your messages' and event_get for 'bus traffic'. There is no ambiguity about when not to call this tool and what to call instead.

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 burden. It does disclose that the operation is READ-ONLY and enumerates the possible status values, which is genuinely useful. However it says nothing about permissions, whether status is eventually consistent, or how 'parked' differs operationally, leaving real behavioral gaps for a no-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 tight clauses with the scope ('you SENT') and the read-only nature front-loaded; every element carries information. The inline set notation is dense but readable.

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

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

For a one-parameter read tool with an output schema, the description supplies scope, the return shape's key fields, and the read-only guarantee, which is enough to call it correctly. The output schema relieves it of explaining return values in detail.

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% and the single parameter's origin (message_id from message_create) is already documented in the schema. The description adds no format or constraint details beyond that, so the baseline 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?

States a specific verb and resource: tracking per-recipient delivery states for a message the caller SENT. The 'you SENT' scoping and the enumerated states (unread/delivered/read/parked) make it distinguishable from generic siblings like message_get or message_list, though no sibling is named directly.

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?

'Track a message you SENT' implies the usage context and requires a message_id from message_create, but there is no explicit when-to-use vs. when-not guidance and no alternative tool named for adjacent needs (e.g., reading message content vs. tracking its delivery).

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 and does so well by disclosing the deterministic failure shape (ok:false, code=MIGRATED), so an agent knows calling it is pointless. It stops short of saying whether the tool is still callable at all or will be removed, but the essential behavior is disclosed.

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 sentences, migration status and replacement named first, mechanical outcome second. 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 zero-parameter deprecation shim with an output schema present, this is fully sufficient: it tells the agent what it is, what it returns, and where to go instead. Nothing needed to decide whether to invoke it is missing.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing to disambiguate. The description correctly implies no inputs are needed.

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 exactly what the tool is (a migrated/deprecated stub) and what it does when called (always returns ok:false code=MIGRATED). It also names the two replacement tools, so an agent can distinguish this from event_wait and inbox_count without opening any 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?

Explicitly routes the agent to alternatives and gives the selecting condition for each: inbox_count for cheap polling, event_wait for explicit blocking. Effectively a when-not-to-use instruction, which is the strongest form of 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?

No annotations exist, so the description carries the full burden. It implies a passive report and notes the features map is 'read-only {feature_*: bool}', but never states side-effect profile, permissions, or cost. With an output schema present the return values needn't be explained, so this is adequate but thin.

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: the enumerated payload is front-loaded and the usage trigger follows. Dense and jargon-heavy, but every clause carries information and nothing is padding.

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

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

An output schema exists, so return shape is covered; the description still summarizes the payload and gives a trigger. For a zero-parameter read-only info tool this is close to complete, with only the safety/permission profile left unstated.

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

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

The tool takes zero parameters, so the baseline is 4 (plus schema coverage is 100%). There is no parameter meaning the description could add.

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 ('Report server versions') and enumerates the exact fields returned (package_version, schema_version, surface_revision, resource_versions, features). It is clearly distinguishable from siblings like capability_list or coordination_health, though it does not name those siblings explicitly.

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 a concrete trigger: 'Call when behaviour disagrees with cached schemas.' That is a real when-to-use condition rather than implied usage. It lacks any when-not guidance or named alternatives, which keeps it out of the top band.

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 load and does disclose real traits: the token is ephemeral, read-only in scope, prefixed nxsept_, bound to the authenticated session, and must not be persisted. It stops short of stating lifetime/expiry or that poll_token_renew exists for rotation, which are the remaining behavioral gaps.

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 the core action front-loaded and the security constraint second; nothing is wasted and no sentence restates the tool name.

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 covers purpose, scope, and handling. It is only marginally incomplete in omitting token lifetime and the renewal path, which an agent would need to avoid misusing an expired token.

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 100% and both parameters are described in the schema as values 'returned by session_open. REQUIRED.' The description adds no parameter-level meaning beyond that, so the baseline 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?

States a specific verb (Issue) plus resource (ephemeral read-only monitor bearer) and scope (this authenticated agent's session workspace). The nxsept_ prefix and 'ephemeral read-only' framing distinguish it from poll_token_revoke and poll_token_renew, though it never names those siblings explicitly.

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 sentence 'Store only in the background monitor; never persist the raw token' gives handling guidance but not selection guidance — it never says when to call this versus poll_token_renew or poll_token_revoke, nor what precondition (an open session) triggers it.

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 the single most important behavioral trait: "The previous raw nxsept_ bearer stops working immediately" — a specific, non-obvious invalidation side effect. It omits auth/permission requirements and failure modes (e.g. no active token), which keeps 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 sentences, front-loaded with the primary action and followed by the single highest-value behavioral fact. No filler, no redundancy, every clause earns its 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?

The tool is simple (2 required params, full schema coverage, output schema present so return values need no explanation) and the description covers the key lifecycle consequence of renewing. It is close to complete, missing only explicit preconditions and when-to-use framing.

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% for both parameters, so the schema already documents session_id and session_secret (including their provenance from session_open). The description adds no format, constraint, or sensitivity detail beyond that, 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 gives a specific verb pair plus resource: "Rotate and extend the active ephemeral poll token for this session." That is well beyond a restatement of the name and clearly separates renew from issue/revoke. It stops short of naming those siblings explicitly, so it lands at 4 rather than 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?

Usage is only implied: the phrase "the active ... token for this session" tells the agent a token must already exist, but there is no explicit when-to-call, no precondition statement, and no routing against poll_token_issue or poll_token_revoke. Minimal viable guidance, nothing more.

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 does not state whether revocation is immediate or permanent, whether an already-revoked or missing token errors, that it requires the session_secret, or what effect revocation has on in-flight polling.

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 front-loaded sentence with no filler. Every word contributes to identifying the action and its scope.

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 presence of an output schema removes the need to describe return values, and the tool is a simple two-parameter revoke. Still, with no annotations and no usage or behavioral context, the description is barely sufficient for an agent to know when revocation is appropriate.

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% and both parameters (session_id, session_secret) are documented in the schema as required values returned by session_open. The description adds no extra meaning beyond the schema, 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 states a specific verb+resource (revoke the active ephemeral poll token) and scopes it to this session, so the action is unambiguous. It does not, however, distinguish itself from the sibling poll_token_issue and poll_token_renew tools, leaving the token lifecycle relationship implicit.

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 guidance, no prerequisites, and no mention of the sibling tools poll_token_issue/poll_token_renew or when revoking should be preferred over letting a token expire. Usage can only be inferred 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?

With no annotations, the description carries the full burden, and it does disclose real behavioral value: idempotency and the exact repeat-call result ('returns ok and stays closed'). It omits the consequential side effects an agent needs before calling — whether closing invalidates tokens, terminates in-flight messages, or requires workspace ownership — so the disclosure is partial.

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 front-loaded sentence with zero filler; the verb and resource lead and the idempotency caveat follows immediately. Nothing could be cut 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?

An output schema exists, so return values need not be explained, and the description covers the key idempotency trait. But with no annotations at all, it should also address the side effects of closing a session and any authorization or scope requirements, which it does 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%, with session_id documented as 'returned by session_open' and workspace_id documented as a scope guard, so the baseline is 3. The description adds no parameter-level meaning beyond what the schema 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?

The description states a specific verb and resource ('Close a session'), which is unambiguous on its own. However, it does nothing to distinguish the tool from close cousins in the sibling list such as session_open and session_heartbeat, so an agent must rely on the name alone to route between session lifecycle tools.

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 guidance on when to close a session versus leaving it open, no prerequisites (e.g. must the session be open?), and no mention of the sibling tools that could be alternatives. The only contextual hint is that repeated calls are safe, which is a behavior note rather than usage 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?

No annotations are provided, so the description carries the full burden, and it does disclose real behavioral traits: membership in the broadcast audience and eviction avoidance via the stale-session reaper. It omits failure behavior (e.g., what happens if the session is already reaped or expired), leaving a gap for a no-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?

A single front-loaded sentence with a semicolon-delimited elaboration; every clause earns its place and nothing is repeated from the schema.

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

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

With an output schema present, the description needn't explain return values, and it correctly references the derived status. The only shortfall is the absence of any guidance on heartbeat cadence or on error/expired-session outcomes.

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 both session_id and workspace_id are already documented in the schema (including the workspace scope-guard rule). The description adds no parameter-level meaning beyond that, making the baseline 3 correct.

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 ('Advance a session heartbeat') and its effect ('report the derived status'), which cleanly separates it from session_open/session_close in the sibling list. It doesn't explicitly name those siblings, so it stops just short of 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 clause 'keeps you PRESENT ... and clear of the stale-session reaper' implies when to call it (to stay alive), but there is no explicit when/when-not guidance or cadence/frequency instruction. Usage must be inferred rather than read.

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