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

No annotations are provided, so the description carries full burden — and it delivers extensively. It documents the keystone (never-authenticated) safety guard, re-assertion inside DELETE, webhook firing, auth generation bump, the one-time/bcrypt/name-scoped/TTL-bound handle verification, the ~30min orphan auto-GC backstop, and the exact return shape plus AUTH_FAILED error conditions.

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

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

Front-loaded with the purpose in the first sentence, then structured when-to-use/when-not, behavior, and returns sections. It's long but every sentence earns its place given the complex safety-critical semantics. Slightly verbose in places but well-organized with clear paragraph divisions.

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 an unusually complex tool (safety-critical deletion, one-time handles, keystone guards, TTL semantics, webhook side effects) with no annotations and no output schema. The description covers all of it: prereqs, failure modes, return values, side effects, and safety guarantees. Nothing material is left undocumented.

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 describes both parameters (name and recovery_handle) thoroughly. The description adds some context (that the handle is name-scoped, one-time, short-lived, returned in register_agent response) but mostly references what the schema already documents, maintaining the baseline.

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

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

The description uses a specific verb+resource ('abandon YOUR OWN botched/orphaned registration') and clearly defines the scope. It distinguishes itself from siblings by explaining this is for unauthenticated orphans where the agent_token was lost post-register, vs unregister_agent which needs the token, and rotate_token for mid-session token loss.

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

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

Explicitly states when to use (orphaned row where token was never captured), when NOT to use (live agent that lost token mid-session, which is refused), and names explicit alternatives (rotate_token, relay recover). Also notes the operator kill endpoint as related context.

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 of behavioral disclosure. It discloses substantial behavior: stores one row per recipient with status='pending', sender excluded, fires one webhook event with delivery_id/idempotency_key in envelope, optional role narrowing, payload cap reference, success/error semantics including count=0 with a note being still success. This is rich behavioral detail. Minor gap: doesn't mention rate limiting specifics or auth mechanism beyond error codes, but these are listed as errors.

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 well-structured with clear sections (When to use, Behavior, Returns, Errors) and is front-loaded with the core purpose in the first sentence. Every sentence adds value: the alternatives, the behavioral guarantees, the return shape, and the error taxonomy. No waste or 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?

This is a complex tool (broadcast fan-out with role filtering, idempotency via webhook envelope, multiple error modes), and no annotations or output schema are provided. The description compensates fully: it documents the return shape including edge case (count=0 with note as success), error codes, behavior guarantees (sender exclusion, one row per recipient, webhook event semantics), and payload limits. This is a complete spec for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so all 4 parameters have schema descriptions. The description adds value beyond the schema: it clarifies that 'role' narrows the recipient set, and that content has the same size cap as send_message (RELAY_MAX_PAYLOAD_BYTES). The agent_token parameter is well-documented in schema with fallback resolution paths. The description doesn't add param-specific detail beyond what schema provides, but schema already covers it thoroughly, making baseline 3-4 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 clearly states the purpose: 'Fan out a single message to every registered agent (or every agent of a given role).' It uses a specific verb ('fan out'), a clear resource (broadcast), and a scoping condition (all agents or by role). It effectively differentiates from siblings like send_message (1:1) and post_to_channel (topical group coordination).

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

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

The description gives explicit when-to-use context ('announcements, fleet-wide pings, role-targeted prompts') and explicitly names alternatives with when-not-to-use conditions: 'For 1:1 use send_message' and 'For topical group coordination prefer post_to_channel' with a rationale (channels persist membership, avoid spamming opted-out agents). This is model 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 behavioral burden — and it delivers well. It discloses what gets created ('channel row and adds creator as a member'), flat topology (no hierarchy), global addressability by name, and required auth capability ('channels'). It even lists all error codes. This is rich behavioral disclosure for a tool with zero annotation coverage.

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

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

The description is structured with clear labeled sections (When to use, Behavior, Returns, Errors), front-loads the core purpose, and every sentence earns its place. No fluff or redundancy; it's information-dense without being bloated.

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 4-param tool with 100% schema coverage, no output schema, and no annotations, this description is remarkably complete. It covers return format, error codes, auth requirements, structural semantics (flat, globally addressable), and positional guidance versus siblings. There are no meaningful gaps for an agent to be confused about.

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% (all 4 params have descriptions in the schema). Despite that, the description adds value by clarifying the name pattern (lowercase, alphanumeric + hyphens) is also echoed in the schema regex, and the agent_token param's optional resolution paths are documented in the schema. The description compensates for auth-related parameter meaning (agent_token) by noting capability requirements, going beyond 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 states a specific verb+resource ('Create a named channel for many-to-many topical coordination') and clearly differentiates from siblings by naming alternatives (send_message, broadcast) with use-case distinction. The purpose is unambiguous and distinguishes this tool from the sibling 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?

Explicit 'When to use' section gives clear use cases (ongoing multi-agent conversations that persist beyond any single agent's lifetime) with concrete examples (#deploys, #triage). Also explicitly states when NOT to use it ('For 1:1 use send_message. For one-shot fleet-wide announcements use broadcast.'), naming alternatives directly.

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 of behavioral disclosure, and it delivers substantially. It explicitly states the destructive nature (removes subscription row AND pending delivery log entries), the auth requirements, exact success/failure return envelopes, the isError:true soft-fail semantics (missing-id surfaces as tool error, NOT a soft-success), and the distinction between error codes and the envelope. The only minor gap is not elaborating on side effects like dependent resources referencing the deleted webhook. No contradiction with any annotation (none exist).

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?

Structured into labeled sections (When to use, Behavior, Returns, Errors) which aids scanning and front-loads the most critical info. At roughly 130 words, it is somewhat long but every section earns its place—the error semantics, in particular, genuinely matter for correct invocation. Slight verbosity in the Returns section where a shorter form would do, but overall well-organized.

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 this is a destructive mutation tool with NO annotations and NO output schema, the description compensates well by documenting side effects (delivery-log cleanup), return envelopes, error semantics, and auth requirements. It covers the essential operational context a caller needs. Minor gaps remain: no mention of idempotency behavior or whether concurrent delete failures occur, but these are edge cases beyond the minimum viable scope.

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%; both parameters (webhook_id, agent_token) already have descriptions in the schema. The description reinforces that agent_token is optional and resolvable from env/header, consistent with schema. It adds marginal value by emphasizing webhook_id is the selection mechanism, but the schema already handles parameter semantics adequately. Baseline 3 is appropriate when 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?

Specific verb ('Tear down') + resource ('webhook subscription') + method of identification ('by id'). Clearly distinguishes from siblings: register_webhook and list_webhooks are creation/listing, while delete_webhook is the teardown counterpart. The description immediately establishes what the tool does without ambiguity.

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

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

Explicit 'When to use' section covers three concrete scenarios: integration retirement, dead receiver URL with delivery-log noise, and secret rotation (delete + register fresh). It implicitly positions this against register_webhook for the rotation use case, offering clear decision guidance. Additionally, it distinguishes auth paths (registrant's token vs cross-owner with webhooks capability) which clarifies authorization context.

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 full burden and delivers: states it's a pure read ('never mutates last_seen'), explains the difference between computed `status` vs operator-controlled `agent_status`, discloses token hashes are stripped (returns `has_token: boolean` only), documents the exact return shape, ordering, and error mode (RATE_LIMITED), plus the notable detail that no auth is required for observability. This is remarkably complete behavioral 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?

Well-organized with clear section labels (When to use, Behavior, Returns, Errors), front-loaded with the core purpose sentence. Every sentence earns its place. Slightly dense in the Behavior section covering multiple concepts, but the structure is clean and scannable, so only a minor deduction.

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 read-only list tool with zero required params and 100% schema coverage, the description is exceptionally thorough: it documents return shape, ordering, error modes, auth posture, security behavior (token stripping), and the semantic distinction between computed vs operator-controlled status fields. Despite no output schema, the description fully compensates by spelling out the response contract.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value on top: explains that `role` is an optional filter, clarifies that `status` is computed while `agent_status` is operator-controlled (differentiating the semantics of what the tool returns). Since all params are already fully documented in the schema at 100% coverage, the description's contributions are bonus context rather than compensation.

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?

Description states the exact verb+resource ('List every registered agent with computed presence + operator-controlled status'), explicitly distinguishes from sibling `get_standup` by naming it and contrasting scope. The phrase 'list every registered agent' with the added detail of computed presence and operator-controlled status makes the purpose concrete and non-tautological.

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

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

Provides explicit 'When to use' guidance with three concrete scenarios (routing target by role, confirming online before sending work, surfacing fleet to dashboard) and an explicit exclusion ('use get_standup instead, it bundles agents + recent activity'). This is textbook usage guidance with clear when-to and when-not-to direction.

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 description carries full burden — and it delivers richly. It discloses the additive/superset constraint (rejecting reductions), the specific error condition REDUCTION_NOT_ALLOWED and NO_OP_EXPANSION, the immutability-gap/CVE rationale, audit-log recording with verified caller name, and token resolution paths (param, env, header). This is comprehensive behavioral disclosure for a mutation tool with zero annotation coverage.

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

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

The description is well-structured with clear labeled sections (When to use, Behavior, Returns, Errors). It is slightly verbose — the CVE/immutability-gap rationale adds some length — but every sentence earns its place by conveying operational constraints. The front-loading of purpose and when-to-use is effective.

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?

Despite having no output schema and no annotations, the description fully specifies the return shape (`{ success, agent, added, capabilities }`), enumerates all error cases with conditions, and covers auth mechanisms. For a mutation tool with behavioral complexity (additive constraint), this is remarkably complete. The version-pinned rationale and audit-log detail fill the gap left by absent annotations.

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 all three parameters including semantics for new_capabilities (superset requirement) and agent_token resolution. The description reinforces the superset constraint and 'added' vs 'capabilities' return distinction, but the parameters themselves are well-covered by the schema. Baseline 3 is appropriate since 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?

The description states a specific verb+resource ('expand capabilities of an agent') and clearly distinguishes the operation from siblings like register_agent and unregister_agent. It identifies the version (v2.1.4), explicitly notes it is self-managed/additive-only, and explains reductions are handled elsewhere. This is a strong, specific purpose statement that differentiates from the sibling registration 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?

The 'When to use' section explicitly names the scenario (agent registered with narrow caps via SessionStart, later needing more like webhooks). It also gives explicit when-not guidance: reductions are NOT supported here and require unregister+register, and it notes there's no admin equivalent by design. This is explicit when/when-not/alternatives 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 provided, the description carries the full burden. It goes well beyond minimal by disclosing the join_time scoping, ordering semantics, idempotency ('fully idempotent'), auth requirement (current member), and error conditions. Slight gap: doesn't explain what happens to messages before join_time beyond 'entitled to see.' Otherwise thorough.

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?

Well-structured with labeled sections (When to use, Behavior, Returns, Errors) and zero filler. Every line earns its place, front-loaded with the core purpose in the first sentence. Appropriate length for a tool that needs to clarify scoping and auth.

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 list-read tool with no output schema, no annotations, and 5 parameters, this description is comprehensive: it documents return shape, message fields, errors, ordering, auth, and scoping. Despite the 5-param schema, the description covers all behavioral aspects an agent needs to correctly invoke and interpret this 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%, so all 5 parameters have schema-level descriptions. The description adds value by tying created_at/ordering to the 'since' parameter's semantics and explaining the join_time scoping inherent to the call. It doesn't restate each schema description but the schema already handles those; the description enriches behavioral context around them.

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?

Clear verb+resource: 'Read the messages you are entitled to see in a channel.' It explicitly distinguishes itself from siblings by naming get_messages (1:1 mailbox) and get_standup (whole-fleet activity), which disambiguates against the closest alternatives.

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 an explicit 'When to use' section listing concrete scenarios (observes channel traffic, dashboard refresh, post-incident thread, role onboarding) and names when NOT to use with alternatives ('For 1:1 mailbox use get_messages; for whole-fleet activity use get_standup'). This is exemplary 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 provided, the description carries the full burden and fully delivers. It discloses atomic mark-as-read semantics, the peek side effect of stamping the observation cursor, per-session read behavior, the distinction between delivery and observation, versioned behavior changes (#198, 3.0.1), response hints, and error codes. This is exceptionally transparent for a tool with significant side-effect complexity.

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 long, but every section earns its place: a crisp one-line summary, a dedicated usage section, behavioral details, return shape, and error codes. It is carefully structured with clear labels and front-loaded with the most essential information. Version markers are compact and do not bloat readability.

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 tool has 8 parameters, complex side effects, session semantics, and no output schema, yet the description covers behavior, return shape, error cases, and alternatives. It explains subtle delivery-vs-observation semantics and what fields like since_bound mean. The description is complete enough for an agent to invoke correctly without further external knowledge.

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

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

The input schema already covers 100% of parameters in detail, so the baseline is 3. The description adds meaningful cross-parameter context beyond schema text, such as how since interacts with pending drains, the hint nudging behavior, and the observation-cursor side effect of peek. The ack parameter remains primarily schema-documented, but the overall description adds enough semantics to warrant a 4.

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

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

The opening phrase 'Drain or peek your own mailbox' is a specific verb-resource pairing that immediately establishes the tool's role. The description then states exactly what it returns ('messages addressed to you, ordered by priority then created_at newest-first') and distinguishes itself from siblings like get_messages_summary and peek_inbox_version.

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 'When to use' section explicitly says 'each turn that should observe new mail' and names concrete alternatives for different scenarios: get_messages_summary for cheaper previews, peek_inbox_version for counts only, and peek=true for surveys that must not consume mail. This is exemplary usage guidance with clear 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?

Despite having no annotations, the description thoroughly discloses behavioral traits: it is non-mutating ('Never marks messages read'), it decrypts on the fly when RELAY_ENCRYPTION_KEY is set, it requires agent token auth (own mailbox only), and it notes the since filter nuance with 'ALREADY-OBSERVED history' and the PENDING drain behavior. This fully covers the behavioral burden, exceeding what annotations would typically provide.

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 well-structured with clear sections: purpose, when-to-use, behavior, returns, and errors. It is informative yet concise, with no redundant sentences. Every sentence adds value (e.g., the content_truncated flag explanation, error codes). The formatting with headers aids readability and scannability.

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 read-only preview tool with 5 parameters, the description is complete: it covers the tool's purpose, usage scenario, behavioral nuances (including tricky since semantics), return format, auth requirements, and error codes. There is no output schema, so the return structure detail is valuable)Skip, and the description fully compensates for the lack of structured output metadata. It is comprehensive enough for an agent to correctly invoke and interpret results.

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 parameters with detailed descriptions, including the complex 'since' semantics and status filter. The description adds a brief note about the same status/since surface as get_messages, but it doesn't go beyond what the schema already explains. Baseline 3 is appropriate since the schema carries the load.

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 clearly states it is a cheap, non-mutating mailbox preview. It distinguishes itself from siblings by explicitly mentioning get_messages as the mutating alternative, and the return structure provides concrete specifics. The verb 'preview' plus the resource 'mailbox' makes the purpose unambiguous.

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

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

The description explicitly states when to use: 'orchestrators scanning many inboxes per cycle, dashboards rendering backlog count, or any flow where you want to see what is there without consuming it.' It also provides a clear alternative: 'After picking interesting IDs, expand them with get_messages (which CAN mutate) or read them by ID.' This gives both positive and negative usage context.

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 excels: it explicitly states the tool NEVER mutates a message, is report-first, and auto-resolves nothing. It details the overdue calculation, auth requirements (agent token, sender-scoped), and error codes including RATE_LIMITED. This is comprehensive behavioral 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?

The description is long but exceptionally well-structured, with clear sections for summary, usage, behavior, return value, and errors. Every sentence adds value, and it front-loads the core purpose immediately. No redundancy or fluff.

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 no output schema and no annotations, the description fully compensates by specifying the return object shape with all fields, explaining the lifecycle states, the overdue flag, and error codes. It is complete for an agent to know exactly what to expect and how to handle errors.

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% with detailed parameter descriptions already present. The description adds minimal extra meaning: it restates the include_resolved semantics and agent_name role but does not significantly go beyond the schema. Baseline 3 is appropriate because 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?

The description opens with a specific verb and resource: 'The SENDER's outstanding-ask recap + the pull source of truth for overdue drift.' It clearly distinguishes this tool from siblings like get_messages or get_messages_summary by focusing on sent asks/obligations, the outstanding set, and the 'PULL' nature versus webhooks. The purpose is unmistakable.

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 'When to use' section explicitly states use cases (orchestrator reconstructing what it is owed on a fresh session or any time needing current picture) and contrasts with webhooks that may be missed. It also explains that LOG messages are excluded and that include_resolved changes the view, providing clear situational 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 delivers thoroughly. It declares 'pure read', explicitly states 'NO LLM on the relay side' (observations are hand-rolled heuristics), details the default filtering behavior (non-offline, flippable via include_offline), documents the auth mechanism ('any agent token'), and lists all error codes. This is exemplary 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?

Well structured with clear labeled sections: When to use, Behavior, Auth, Returns, Errors. Every sentence earns its place — no filler, each line conveys operational information an agent needs. Front-loaded with the core purpose and usage decision, then behavioral details, then error contract.

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

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

For a tool with nested objects, 3 params, no output schema, and no annotations, this description is exhaustive. It defines the complete return structure, ALL error modes, authentication requirements, filtering semantics, and a nuanced behavioral caveat (heuristic observations, no LLM server-side). Nothing material is left ambiguous for correct invocation and result interpretation.

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 documents all params. The description adds meaningful semantic value on top: it explains the since values, defines what include_offline flips in the default behavior, specifies that agents/roles narrow the snapshot and AND together, and rejects the agent_token parameter since it's noted optional. It adds real context beyond the schema's field descriptions.

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

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

The description is highly specific: 'One-shot team-status synthesis for orchestrators' with a clear verb-resource pair (get + standup/rollup). It explicitly defines the return contract (active_agents, message_activity, task_state, observations), distinguishes its server-side aggregation role from sibling tools, and names alternative tools to fall through to. This belongs in the Tier A category.

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?

Excellent when/when-not guidance. It states explicitly to use this instead of chaining discover_agents + get_messages + get_tasks, points out the token-efficiency rationale, and instructs to 'fall through to the underlying tools' for drill-downs. It also enumerates all error types, giving the agent actionable preconditions.

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 so thoroughly. It discloses pure-read behavior, decryption-on-the-fly, and critically the auth restriction (agent must be requester or assignee; relay refuses third-party leaks). It even enumerates the actual error codes (NOT_PARTY, NOT_FOUND, RATE_LIMITED), which is rich behavioral disclosure beyond any annotation could offer.

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?

Well-organized with clear section headers (When to use, Behavior, Returns, Errors). Every sentence earns its place — no filler, no repetition beyond the intentional emphasis of return payload. Efficient and front-loaded.

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

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

For a single-row lookup with no output schema, this description is remarkably complete: it specifies the return shape ({ success: true, task: TaskRecord }), the decryption behavior, auth constraints, and all error conditions. Nothing material is left to guesswork.

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 both parameters well. The description adds some context by tying task_id to the post_task response and noting agent_token is optional/resolvable from env or header, which is useful. This is above the baseline 3 for full coverage but not extensive extra semantics.

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 ('Look up a single task by id') and clearly distinguishes from sibling get_tasks (singular vs many). The purpose is unambiguous and the tool's niche is well defined.

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 'When to use' section gives concrete scenarios (heartbeat confirmation, checking a known task_id from post_task), and names the alternative get_tasks for browsing many tasks. Provides clear when-to-use/when-not-to 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 were provided, so the description carries the full burden. It explicitly declares 'pure read' behavior, explains ordering (priority then created_at newest-first), auth requirements (agent token, only own tasks), and documents the default filter value (status='all'). It does not disclose pagination behavior beyond the limit param, and error codes are listed. Very strong for an unannotated tool, though it could mention whether pagination/cursor exists.

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

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

The description is structured with clear labeled sections (When to use, Behavior, Returns, Errors). Every sentence earns its place with informative content. It is comprehensive yet tightly organized, with no fluff or repetition. Excellent use of section headers for scannability.

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 5-parameter query tool with no output schema, the description is quite thorough. It documents return shape (tasks, count, agent, role, filter with per-task fields listed), auth model, ordering, defaults, and error codes. Given the rich parameter set and the description's good coverage, it's close to complete. Minor gaps: no pagination explanation and limit behavior is only in the schema, but these are adequately covered by schema descriptions.

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 fully documents all 5 parameters. The description adds context by clarifying the meaning of role enum values ('assigned' = tasks for you, 'posted' = tasks you created) which echoes the schema. It reinforces the default status='all' behavior. The description adds marginal value beyond the thorough schema but does not introduce new parameter information. 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 clearly states the verb+resource: 'Query the tasks you are involved with.' It differentiates from siblings by explicitly naming get_task (single task by id) and get_standup (team-wide rollup), and distinguishes roles ('assigned' vs 'posted'). This is a specific and unambiguous purpose definition.

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

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

Provides explicit when-to-use guidance: assignees triaging their queue (role='assigned') and requesters checking on dispatched work (role='posted'). It also names alternatives (get_task for single task, get_standup for team-wide rollup) and explains auth scoping (only your own tasks visible). This is exemplary usage guidance with both usage cases and 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?

No annotations exist, so the description carries the full burden, and it delivers: declares 'pure read' behavior, lists exactly what is returned including the detailed return object fields, discloses token-based conditional behavior, and states 'Errors: none expected'. Very thorough behavioral disclosure given zero annotation support.

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?

Well front-loaded with a one-line summary, then clear labeled sections (When to use, Behavior, Returns, Errors). Every sentence earns its place—no filler, efficient use of paragraphs and code formatting for the return shape.

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 read-only health check with one optional param and no output schema, the description fully specifies the return shape, error behavior, transport compat, and token handling. Nothing material is missing; it's complete for its complexity level.

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 the single optional parameter. The description adds context by noting the token is 'also resolvable from RELAY_AGENT_TOKEN env or X-Agent-Token header', going beyond the schema's own description. This is a small refinement over a strong 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 uses a specific verb+resource ('Report relay process health + live counts') and clearly distinguishes from siblings, notably naming get_standup as the heavier alternative ('Cheaper than get_standup for binary up/down questions'). The scope of what's counted (agents, messages, tasks, channels, webhooks) is explicit.

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

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

Explicitly states when to use ('liveness probes', 'version-pinning checks', 'dashboard footers') and provides a direct comparison with get_standup including a cost/benefit rationale. It also notes transport compatibility (stdio AND HTTP) and that no capability is required, giving complete selection 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 provided, the description carries full behavioral disclosure burden and delivers richly: it explains the joined_at = now semantics, the non-replay of historical traffic ('streams, not archives'), idempotency ('rejoining is a no-op'), auth requirements (any agent token), return shape including joined=false case, and full error catalog (AUTH_FAILED, NOT_FOUND, RATE_LIMITED). This is exemplary transparency.

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 well-structured with clear sections (When to use, Behavior, Returns, Errors) and fronts the core purpose immediately. It's longer than minimal, but every sentence earns its place given the behavioral nuances it explains; no filler or 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?

For a 3-param tool with no output schema and no annotations, the description is remarkably complete: it covers auth, idempotency, event semantics, return format including edge cases, error codes, and temporal behavior. Nothing material is left unstated for an agent to invoke this correctly.

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

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

Schema coverage is 100% so the baseline is 3. The description adds semantics around agent_name (who is joining) and channel_name (which channel to subscribe to) but the schema already documents each parameter adequately. The description adds the 'joined' return semantics for interpreting the join result but doesn't add much per-parameter meaning 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 opens with a specific verb+resource ('Subscribe to a channel so you receive its messages from your join time forward'), clearly distinguishing it from siblings like post_to_channel and get_channel_messages. It explicitly positions itself against related channel tools, making the purpose unmistakable.

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 explicitly states 'When to use' (follow a channel's traffic), provides alternatives ('Pair with post_to_channel... and get_channel_messages'), and explains that joining is open to any authenticated caller with no invite gate. This is model-tier 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 provided, the description carries the full burden and delivers richly: discloses that the membership row is removed, past messages persist, the joined_at cursor is forgotten, auth is per-agent token with a self-only limitation, and even the exact return shape with semantics for left=false. Error list (AUTH_FAILED, NOT_FOUND, RATE_LIMITED) adds agent-relevant expectations. This is exemplary transparency.

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?

Structured with clear labeled sections (When to use, Behavior, Returns, Errors). Every sentence carries distinct information with zero filler. Front-loaded with the core function in the first line, then efficient structured detail. Well-sized for the complexity of the tool.

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

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

No output schema exists, so the description properly explains the return shape ({success, channel_name, agent_name, left, note}) with semantics for left=false. Auth requirements, idempotency, error responses, and side effects on the observation window are all covered. For a mutating tool with no annotations, 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?

Schema coverage is 100%, so the baseline is 3. The schema already documents each of the three parameters clearly (channel to leave, agent leaving, token resolution options). The description adds the auth context (agent token resolution paths) that enriches the agent_token param but doesn't add meaning substantially beyond the schema since coverage is already complete.

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

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

The description uses a clear verb+resource pairing ('Cancel your membership') and states the tool's effect ('stop receiving a channel's messages'). It clearly distinguishes from siblings like join_channel and post_to_channel by focusing on leaving. The purpose is immediately obvious and unambiguous.

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

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

Provides explicit when-to-use guidance: 'channel is no longer relevant to your role' and 'shutting down and want to be a clean citizen'. Note about idempotency ('calling it on a channel you never joined is fine') gives clear what-happens-when guidance. It also references siblings implicitly through the fresh observation window note about join_channel.

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 explicitly states this is a pure read, that the raw HMAC secret is never returned (only has_secret boolean), specifies auth requirements (any registered agent), and discloses errors like AUTH_FAILED and RATE_LIMITED. This is thorough behavioral disclosure for a read tool.

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

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

The description is tightly organized with clearly labeled sections (When to use, Behavior, Returns, Errors). Every sentence delivers distinct value — no filler, no redundancy with the schema. It front-loads the core purpose and groups related information efficiently.

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-read tool with 100% schema coverage on its single optional param, this description is complete. It covers purpose, usage context, security guarantees, auth model, return format, and error codes. An output schema is absent, so specifying the exact return shape is appropriate and enhances 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?

The single parameter agent_token has 100% schema coverage in the schema. The description adds clarity by explaining it's optional and resolvable via env var or header. Since schema coverage is high, the baseline is 3, and the extra context about alternative resolution methods earns a 4.

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 clearly states the tool lists every webhook subscription on the relay. It uses a specific verb+resource combination and differentiates from siblings like register_webhook and delete_webhook by describing the read/list nature. The return shape and event filtering are explicit.

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 concrete when-to-use scenarios (sanity-checking integrations, pre-cleanup audits, admin UI) and notes client-side filtering limitation for narrowing by event. It doesn't explicitly name an alternative tool for server-side filtering, but the context of siblings is sufficient to guide 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 full burden. It thoroughly discloses: pure read (non-mutating), the semantics of each return field (epoch rotation on backup/restore, last_seq only advances on read-cursor, total_unread_count advances on every send), required reset behavior on epoch mismatch, auth requirements (any agent token), and possible error codes.

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?

Structure is exemplary — sections for when-to-use, behavior, returns, and errors are clearly delineated. Every sentence earns its place; the behavioral semantics around epoch, last_seq, and total_unread_count are dense but essential. No fluff.

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 no-output-schema, no-annotation tool, the description is remarkably complete. It explains error types, auth requirements, the full return shape, subtle cursor/epoch semantics, a concrete usage pattern, and a wake integration. An agent has everything needed to call this correctly and interpret results.

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 documents both parameters. The description adds context about agent_token ('Optional here — also resolvable from RELAY_AGENT_TOKEN env or X-Agent-Token header'), which goes beyond the raw schema. It doesn't add much beyond that, which is acceptable given perfect schema coverage.

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 clearly states the tool's purpose: a 'Cheap non-mutating mailbox version probe' that checks for new mail without a full get_messages round-trip. It explicitly distinguishes from siblings like get_messages and get_messages_summary, and the specific return fields are enumerated.

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

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

Provides explicit when-to-use ('low-rate polling that wants to know ‘do I have new mail?’'), how to use it (diff total_unread_count against cached value), a wake integration pattern, and explicit alternatives ('use get_messages (mutating) or get_messages_summary (preview)'). This is model guidance for when-not-to-use too.

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 of disclosure, and it delivers well. It explains the created row's initial status ('posted'), the webhook notification (`task.posted`), the heartbeat lease mechanism with `RELAY_TASK_LEASE_SECONDS`, the health monitor surfacing stuck tasks, auth requirements (requester token; `to` must be registered), and the return envelope. This is rich behavioral context, though it omits details like idempotency or whether re-posting to the same agent is allowed.

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 well-structured with bolded section labels (When to use, Behavior, Auth, Returns, Errors) making it highly scannable. Every sentence earns its place — lifecycle, webhook, heartbeat, auth, return shape, and errors are each covered in one compact paragraph. No redundancy or 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 7-parameter tool with no annotations and no output schema, the description is exceptionally complete. It documents the full behavioral lifecycle (post→accept→complete/reject/cancel), the return envelope shape, error codes, auth model, and adjacent tools. Given the tool's moderate complexity, nothing critical 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 coverage is 100%, so the baseline is 3. The description adds value by explaining behavioral meaning of parameters beyond schema types: `to` must be a 'registered agent', `priority` maps into the returned status/task, and `schema_id` is contextualized via 'v2.10' note and 'schema-gated completion' semantics. However, most parameter details (max lengths, defaults) remain in the schema, so the incremental semantic addition is moderate.

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+resource statement: 'Assign a tracked task to a specific agent.' It clearly distinguishes from `post_task_auto` (auto-pickup) and `send_message` (free-text) by name. The task lifecycle (accept/complete/reject/cancel) is explicitly documented, making the tool's purpose unambiguous against 30+ sibling 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?

The 'When to use' section explicitly states when to use this tool (work needing accept→complete/reject state machine with single owner) and when NOT to use it, naming concrete alternatives: `post_task_auto` for anyone-capable pickup and `send_message` for free-text comms. It also documents the assignee/assigner interaction flow via `update_task`, giving clear usage context.

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 burden. It thoroughly discloses the routing algorithm (smallest accepted-task backlog, superset matching, freshest last_seen tie-break), the queued/auto-assign path via register_agent, sender exclusion, and the return contract. It also lists error codes. Minor gap: no mention of rate-limit specifics or auth requirements beyond token resolution.

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?

Well-structured with labeled sections (When to use, Behavior, Returns, Errors), front-loaded with the purpose. Each sentence earns its place, and the labeled sections make scanning efficient despite its length.

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?

Complete for a routing tool with 7 params at 100% schema coverage. The no-output-schema gap is compensated by a detailed return contract, and the queuing/auto-assignment behavior is fully explained. The v2.0/v2.1 versioning is clearly documented.

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 baseline is 3. The description adds value by clarifying `allow_self_assign` semantics (v2.1 opt-in, sender exclusion rationale) and `required_capabilities` dual role (routing plus queue auto-assignment). It also explains the return-value semantics for `routed`/`queued` paths beyond what the schema 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?

Description states specific verb+resource ('auto-route a task to the least-loaded capable agent') with versioning (v2.0). It distinguishes from siblings by naming `post_task` (intentional assignee) and `broadcast` (non-tracked notifications). Clearly differentiates its auto-routing role from the other task 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?

Explicit 'When to use' section states the tool is for when capabilities are known but assignee is not, with load balancing. Excludes `post_task` for intentional assignees and `broadcast` for non-tracked notifications. Also documents the v2.1 `allow_self_assign` opt-in behavior.

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 full responsibility for behavioral disclosure. It does well: explains exact-match lookup behavior, fan-out semantics (one row per owner with routed_capability stamp), fire-and-forget (NOT queued-until-owner, no owner → routed_to:[] and nothing stored), webhook firing, encryption-at-rest conditionality, the exclude_self default behavior, and the distinction from point-to-point triggering. It even discloses the return shape. The only minor gap is no explicit side-effect/airtable-style side effect discussion, but the fire-and-forget disclosure is thorough.

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 well-structured with clear labeled sections (When to use, Behavior, Returns, Errors) and front-loaded purpose. Despite covering considerable ground, every sentence earns its place — no filler. The section headers make it scannable for an agent parsing behavior quickly.

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

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

Given the tool's moderate complexity (6 params, routing semantics, ambiguous lane behavior), the description is remarkably complete. It explains the return contract, error conditions, edge cases (no owner), auth resolution paths, encryption behavior, and how recipients read messages. Since there's no output schema, the explicit Returns section covers that gap well. No significant missing information 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 baseline is 3. The description adds modest value: it clarifies the lane semantics for reading recipients (lane='capability'), explains exclude_self's default behavior, and references RELAY_ENCRYPTION_KEY/RELAY_MAX_PAYLOAD_BYTES context. However, most parameter meaning is already well-documented in the schema itself, so the description doesn't dramatically elevate beyond baseline.

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 clearly states what the tool does: routes an FYI/coordination message to the current owner(s) of a capability. It uses a specific verb+resource construction ('Route... to the current owner(s)') and explicitly distinguishes it from send_message (point-to-point) and post_task_auto (task posting), showing clear sibling differentiation within the same messaging family.

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 excellent when-to-use guidance: 'surface a finding, status, or cross-cutting update to whoever owns a domain WITHOUT knowing their name.' It explicitly states what should NOT use this tool (action-required completions MUST stay point-to-point via send_message, noting the reliability trigger implication) and names the alternative (send_message). This is exemplary usage guidance with explicit 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 provided, the description carries the full burden and does so thoroughly: it discloses the storage side effects (channel_messages row, webhook event, visibility in get_channel_messages with a joined_at filter), payload cap, encryption-at-rest behavior, and detailed auth requirements (current member + channels capability). Also enumerates all error cases.

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?

Every sentence earns its place: purpose, when-to-use, behavior, auth, returns, and errors are each one focused line. Front-loaded with the action, and tightly structured with labeled sections. Zero 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?

Despite high complexity (5 params, 5 error states, auth requirements, side effects, and no output schema or annotations to fall back on), the description covers everything needed: return shape, error conditions, behavior, and alternatives. Complete and self-sufficient for a mutation 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%, so baseline is 3. The description adds meaningful value beyond the schema by explaining the RELAY_MAX_PAYLOAD_BYTES cap tied to content, the resolution order for agent_token (explicit > env > header), and the audience semantics tied to channel_name. This elevates it above baseline.

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 ('Send a message into a channel you have joined') and clearly distinguishes it from siblings — send_message for 1:1, broadcast for fleet-wide one-shots. It precisely scopes the audience to current channel membership at post time.

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

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

Explicitly states when to use ('ongoing topical coordination among multiple agents') and names two concrete alternatives (send_message for 1:1, broadcast for fleet-wide one-shots), plus clarifies audience scope. This is a textbook example of 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 provided, the description carries the full burden — and it excels. It discloses idempotency, token issuance (minted ONCE, stored in RELAY_AGENT_TOKEN), token preservation on re-register, capability immutability, recovery_token flow, CAS takeover semantics (force/expected_session_id), and specific error codes. Exceptionally thorough behavioral 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?

The description is well-structured with clear sections (When to use, Behavior, Returns, Errors) and front-loads the core purpose. It is somewhat long, but every paragraph earns its place — each covers a distinct behavioral aspect (idempotency, token lifecycle, return fields, error taxonomy). Arguably dense but not padded.

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

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

For a 16-parameter, high-complexity tool with no output schema and no annotations, the description is remarkably complete. It documents return shape (agent, protocol_version, agent_token, auth_note, capabilities_note, auto_assigned_tasks, recovery_completed), error taxonomy with all four codes, and usage guidance. The agents' expected behavior is fully specified despite the enormous schema surface.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context about key parameters (name, capabilities immutability, token) but the schema already documents each of the 16 parameters richly with version tags, ADR references, and mutation rules. The description does not need to add much beyond what the schema 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?

The description opens with a specific, action-oriented statement: "Register this terminal as a named agent so other agents can address it." This clearly states the verb (register), resource (terminal/agent), and purpose (addressability by other agents). It distinguishes from siblings like unregister_agent, abandon_registration, and expand_capabilities.

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 "When to use" section says to call first in any session needing to send/receive messages, post tasks, or join channels. It notes idempotency (safe on reconnect), mentions the SessionStart hook that typically handles it, and implicitly distinguishes re-registration (register_agent) from expansion (expand_capabilities).

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 were provided, so the description carries the full burden. It discloses immutability (re-registering an id is refused), hardening behaviors ($ref/$dynamicRef/$recursiveRef/$data rejected, meta-validation before ajv compile), auth requirement, and explains the compile-time attack surface rationale. It doesn't explicitly state whether this is read-only vs mutating, but 'register' + immutability context makes the write nature 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?

Well-structured with clear section headers (When to use, Behavior, Returns, Errors). Every section earns its place, and errors are enumerated. The version tag 'v2.10 — safety' adds perspective on the tool's maturity context. No fluff.

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

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

No output schema exists, so the description compensates by listing the exact return shape ({ success, id, created_by, created_at, note }) and all error codes. For a 4-param tool with 100% schema coverage and nested objects, this is thorough. Could mention pagination or the max number of schemas, but that's a minor omission given all else.

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 baseline is 3. The description adds value by clarifying that json_schema rejects $ref-family keywords and is meta-validated/hardened, and that agent_token is optional (resolvable from env or header). Minor gap: no guidance on name uniqueness semantics beyond what's in 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?

Specific verb+resource: 'Register a reusable, immutable JSON Schema that gates task completion (v2.10 — safety).' It clearly distinguishes from siblings like task_schema_get (retrieval) and post_task (which just attaches a schema). The domain use case is explicit.

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?

Has an explicit 'When to use' section with a concrete example, explains the lifecycle (requester attaches via post_task's schema_id, assignee's update_task validates), and lists built-in schemas that are auto-registered, helping the agent avoid redundant registration. Auth requirement (manage_schemas) is stated.

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

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

With zero annotations provided, the description carries full burden and succeeds: it discloses encryption-at-rest of the HMAC secret with keyring details, the delivery headers (X-Relay-Delivery-ID, X-Relay-Idempotency-Key, X-Relay-Signature), SSRF validation against cloud-metadata/private-IP blocklist, the full event list, the return envelope shape, and all error codes with causes. This is exemplary behavioral disclosure for a tool with no annotations.

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

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

Well-structured with labeled sub-sections (When to use, Behavior, Events, Returns, Errors) that front-load the purpose and usage before deep behavioral detail. Every sentence earns its place, though the length is substantial — justified given the tool's complexity and zero annotations, but slightly more than strictly minimal.

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 5-param, 2-required tool with no output schema and no annotations, the description is remarkably complete: it covers the output envelope, all error modes, security behaviors, event taxonomy, idempotency headers, and alternative tools. There are no significant information gaps an agent would need to guess at.

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 parameters are documented in schema. The description adds meaningful context beyond the schema: the filter's mechanism ('narrows by sender/recipient') amplifies the schema's agent-name description, and the 'optional * wildcard' behavior is integrated. The secret's return-field interplay (has_secret) is disclosed. Minor credit withheld only because most param semantics already live in the schema, which the description appropriately acknowledges.

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?

Description states a specific verb+resource ('Subscribe an HTTP endpoint to relay events') that clearly differentiates from siblings like list_webhooks and delete_webhook, and identifies the subscribed event types. It enumerates the full event taxonomy and filter capability, leaving no ambiguity about what the tool does.

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 'When to use' section names reactive integration scenarios (Slack notifier, audit pipeline) and contrasts against alternatives: 'For polling-style observation prefer get_standup or peek_inbox_version' and notes /dashboard already consumes live events. This gives clear when-to and when-not-to 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 were provided, so the description carries the full burden. It thoroughly discloses behavior: updates agent_pid + agent_pid_start and fills host_id when NULL, does NOT rotate session_id, does not bump last_seen or touch read cursor, is idempotent, and requires own agent token only. Returns and errors are documented.

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 well-organized with labeled sections (When to use, Behavior, Returns, Errors) and is front-loaded with the core purpose. It could be mildly trimmed—the Returns/Errors sections are partly visible in schema contexts—but each 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?

For a simple metadata-only self-report with 100% schema coverage and no output schema, the description is remarkably complete. It covers when to use, behavior, idempotency, auth requirements, return shape, and error cases—more than sufficient for correct invocation and 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 description coverage is 100%, so the schema already documents all 4 parameters thoroughly. The description adds context about liveness semantics (restamping same values is a no-op, PID-liveness only when start-time is null) which enriches the parameter meaning beyond what schema 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?

The description states a specific verb+resource ('Restamp your own liveness anchor — agent_pid + process start-time') with a narrow, well-scoped metadata-only self-report. It clearly distinguishes this from siblings like register_agent by explicitly noting it rotates session_id while this does 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?

Explicit 'When to use' section explains that hooks call this automatically, and contrasts it directly with register_agent which rotates session_id and can re-surface already-read mail. Also states 'You rarely call it by hand', giving clear when-to/not-to 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 were provided, so the description carries full disclosure burden — and it delivers thoroughly. It specifies the exact DB operation (sets resolved_at=now() WHERE to_agent is you AND not already resolved, one transaction), side effects (does NOT mark read, does NOT delete), idempotency (silent skip semantics), recipient scoping (token bound to agent_name, DB filters by to_agent), and the full error set (AUTH_FAILED, VALIDATION, RATE_LIMITED).

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 organized with clear labeled sections (When to use, Behavior, Returns, Errors) and is front-loaded with the core purpose. It's prose-dense and longer than the TDQS 4.3 exemplar, but every sentence earns its place given the semantic weight of read-vs-resolve-vs-ack. Slight verbosity around the read/resolved contrast, but it's genuinely informative.

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 mutating, permission-scoped tool with no output schema and no annotations — the highest-risk category. The description covers the transactional atomicity, idempotency, recipient scoping, return-shape semantics (including the count mismatch meaning), and error handling. Nothing material is left ambiguous for an agent to safely invoke this 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%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains the resolved_count < requested_count asymmetry, the idempotent skip behavior for unknown/foreign ids, and the auth-fallback chain for agent_token (token param vs env var vs header). This elevates it above baseline.

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 clearly states the verb (resolve/ack), the resource (specific messages), and the durable outcome ('leave your pending queue for good'). It also specifies a version (v2.12.0). It powerfully distinguishes from siblings by contrasting with read (session-INDEPENDENT vs per-session) and with get_messages (one-call drain vs partial).

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 'When to use: PARTIAL handling' section gives precise decision context. It names the alternative get_messages(status='pending', ack=true) for the 'handled everything' path, and explains the read vs resolved duality so an agent knows which tool fits which scenario. This is model decision 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 fully discloses behavior: state transitions, token_hash preservation, vault file scrubbing, capability requirements, idempotent no-op, and error codes. This goes far beyond what annotations would typically provide.

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?

Organized into labeled sections (when to use, behavior, returns, errors) with every sentence providing necessary detail. The length is justified by the tool's security-critical nature and complex semantics.

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 description covers prerequisites, alternatives, return data, errors, and side effects. Since there is no output schema, the detailed 'Returns' section is essential and fully provided.

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

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

The input schema already describes all parameters with 100% coverage. The description reinforces the issue_recovery flag's effect but does not add significant new parameter-level meaning 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 opening line 'Invalidate another agent's token' clearly names the action and object. It explicitly contrasts with rotate_token/rotate_token_admin and unregister_agent, distinguishing it from sibling 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?

Provides explicit when-to-use scenarios ('confirmed compromise, lost device, or graceful retirement') and directs users to alternative tools for different use cases, making the choice 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 provided, so the description carries full burden and delivers richly. Discloses prerequisite (current valid token), grace-window mechanics for managed agents (both tokens valid, push-message carries new token), immediate invalidation for unmanaged, and state-specific behavior. Documents exact return shapes for each agent class.

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?

Well-organized with clear paragraphs for when-to-use, behavior, returns, and errors. Front-loaded with the one-line purpose. Slightly lengthy but every section adds distinct information; the detail about return variants is justified for a tool with nuanced behavior.

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

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

No output schema exists, so the description must document return values, and it does so exhaustively for all three agent-class variants. Also documents the error codes with state-specific handling. For a tool with this behavioral complexity (3 agent classes, grace windows, CAS races), the description is remarkably complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining grace_seconds' clamp behavior relevance and that unmanaged agents ignore it, plus alternative token resolution routes (env var, header) beyond the schema note. Slight deduction for not elaborating on agent_name semantics beyond what the schema 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?

Clear verb+resource+scope: 'Self-rotate your own agent_token (v2.1)'. Explicitly contrasts with siblings: distinguishes from rotate_token_admin (admin-driven rotation of others) and revoke_token (wiping entirely). Strong differentiation.

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

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

Explicitly lists when to use (scheduled rotation, suspected leak, fresh secret without losing identity) and names specific alternatives with precise conditions (rotate_token_admin for admin-driven, revoke_token for wiping). Also details managed vs unmanaged behavior context.

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 full burden and delivers rich detail: explains the Managed-vs-unmanaged behavioral split, describes token delivery mechanisms (push-message + grace window vs return-in-response), notes `restart_required:true` for unmanaged, and discloses that audit logs record BOTH rotator and target for attribution. It also enumerates full error taxonomy. Only minor gap: doesn't disclose whether operation is destructive/irreversible in explicit terms, though hard-cut grace=0 implies 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?

Well-structured with clear semantic sections (When to use, Behavior, Returns, Errors) using bolded labels. Each sentence earns its place, front-loaded with the core action. The error taxonomy and return shapes are compactly enumerated without fluff. Zero filler 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 4-parameter, no-output-schema, no-annotation tool, the description is thoroughly complete: covers purpose, when/how to use, behavioral nuances, exact return shapes for each branch (managed-with-grace, managed-with-zero-grace, unmanaged), and all error conditions. Nothing meaningful is left unspecified for the agent to guess.

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 baseline is 3. The description adds value by explaining the distinction between rotator and target (self-rotation uses rotate_token), clarifying grace_seconds semantics (clamped, forced hard-cut at 0, ignored by unmanaged), and noting agent_token can come from multiple sources. It adds meaning beyond the field descriptions.

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

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

The description clearly states the action ('Admin-initiated rotation of another agent's token') with a specific verb and resource, and names the phase (v2.1 Phase 4b.2). It distinguishes from siblings by explicitly naming rotate_token (self-service) and revoke_token (revocation), and differentiating against the target_agent_name schema constraint.

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

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

Provides explicit when-to-use scenarios ('operator-driven incident response, scheduled rotation across the fleet, or onboarding a Managed agent'), states the prerequisite capability (`rotate_others`), and names explicit alternatives for different cases (rotate_token for self-service, revoke_token for revocation without re-issuance). This is model-level 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 fully discloses behavior: stores message with 'status=pending', notifies webhook subscribers, recipient sees it on next get_messages, auto-marks read unless peek=true, encryption at rest, payload caps, and auth requirements. It also lists probable errors, making the tool's behavior transparent.

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 well-structured with clear sections: 'When to use', 'Behavior', 'Returns', 'Errors'. It is concise yet comprehensive, with every sentence providing value. No redundancy or 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 tool with 8 parameters, no output schema, and no annotations, the description is remarkably complete. It explains the return format, error cases, storage behavior, encryption, and payload limits, giving an agent all necessary context to invoke it correctly. Alternatives and usage scenarios are also covered.

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 parameters are already documented in the schema. The description does not add significant new semantics beyond the schema; it mentions the `content`/`message` alias and the disposition field, but these are already in the schema descriptions. Thus the baseline score 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?

The description opens with 'Send a text message addressed to a single agent,' using a specific verb and resource. It then distinguishes from siblings by explicitly naming `broadcast`, `post_to_channel`, and `post_task` as alternatives for different scenarios.

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 'When to use' section provides explicit guidance: 1:1 communication, dispatching work, relaying updates, asking questions. It also gives clear exclusions and alternatives, such as 'Prefer `broadcast` for fan-out to many agents, `post_to_channel` for topical group coordination, and `post_task` when the recipient should track state-machine progress.'

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 disclosure burden and delivers richly: it states no WebSocket push exists (already-open dashboards need full reload), describes auth requirements as admin-level capability, enumerates all three error codes, and details what gets stored in dashboard_prefs. This far exceeds the minimal burden.

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 thorough and well-organized with clear labeled sections (When to use, Behavior, Returns, Errors), which aids agent scanning. It's somewhat longer than the TDQS high examples but every sentence earns its place given the behavioral complexity of custom mode and the absence of 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?

For a tool with 3 params (one nested object), no annotations, and no output schema, the description covers all bases: purpose, when/when-not, behavior, storage location, auth, error taxonomy, and return shape. Fully complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value: it clarifies that catppuccin is the default, names the Mocha palette, and specifies that custom mode requires all 13 CSS tokens. It adds contextual meaning about mode semantics that the schema enum alone doesn't convey.

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 clearly states it sets the server-side default dashboard theme, with a specific verb+resource. It distinguishes this tool from siblings by explicitly targeting org-level theme defaults and first-visit theming, which none of the sibling tools (which are messaging, task, and agent-management focused) cover.

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 'When to use' section explicitly names the two scenarios (org-level defaults, brand palette via custom mode), and even explains the exclusion — that individual operator localStorage preferences override this default for repeat visits. This is explicit usage guidance with clear context.

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?

Rich behavioral detail: health-monitor reassignment exemption, enum aliasing (busy/away→working), auth requirements (own token only), and error codes. However, no annotations are provided, so the description carries the full burden; it does disclose mutation, auth, and enum-widening. The mapping details add significant value beyond just 'declares status'.

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?

Well-structured with labeled sections (When to use, Behavior, Returns, Errors) that front-load the critical decision context. Slightly verbose in places but every sentence earns its place with concrete operational details like the enum mapping and version reference.

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?

Complete for a state-setting tool: describes behavior, health-monitor implications, return shape, error codes, and auth requirements. Given no output schema, the Returns section compensates by documenting the response shape. No annotations require additional disclosure.

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 description adds substantial semantic value: it explains the legacy alias mapping (online→idle, busy→working, away→blocked), notes which statuses exempt from reassignment, and clarifies which values are relay-computed vs agent-settable. Also explains the optional agent_token resolution chain via env/header.

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?

Declares operational state distinct from presence, with explicit verb (declare, set) and resource (agent_status). Explicitly differentiates from last_seen-derived presence and identifies sibling get_standup for rollup use. Purpose is specific and clear.

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 'When to use' section states the context (tell the relay what kind of work you're in for health monitor/orchestrator routing) and explicitly distinguishes from last_seen-derived presence and names the alternative get_standup. Provides clear when-use and when-not-use 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. It thoroughly discloses: pre-registration server-side, token minting timing and delivery via env/vault, AppleScript UI opening, return payload structure, the one-time visibility of agent_token, the stdio-vs-HTTP credential gate (R3 transport gate), and specific error codes. This is comprehensive behavioral disclosure for a complex orchestration tool.

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

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

The description is dense but front-loaded with the one-line purpose then 'When to use,' 'Behavior,' 'Returns,' and 'Errors' sections. Every section earns its place given the tool's complexity (platform constraints, token handling, transport gates). It's long but structured clearly with leading headers; could be slightly tighter but is well organized.

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

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

This is a complex 8-parameter tool with no annotations, no output schema, and platform-specific behavior. The description covers purpose, when-to-use, behavioral details (token lifecycle, vault, transport differences), return shape, error cases, and parameter trade-offs (brief_file_path vs initial_message). For a tool this complex, the description is remarkably complete.

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

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

Schema description coverage is 100%, so all 8 parameters are already documented in the schema. The description adds cross-cutting guidance (brief_file_path preferred over initial_message for non-trivial scopes, brief file validation limits <=10KB). This adds value beyond the schema but the baseline-3 is appropriate since the schema already covers each parameter's semantics.

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 very specific action: 'Open a new Claude Code terminal pre-configured as a relay agent (macOS only).' This clearly differentiates from siblings like register_agent (registration), send_message (comm), and post_task (tasking). The verb+resource+scope is specific and unambiguous.

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

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

The description explicitly states 'When to use: orchestrators delegating work to a fresh sub-agent.' It also notes the platform constraint (macOS only, Linux/Windows drivers exist for smoke tests but don't open UI), and distinguishes brief_file_path vs initial_message with clear preference guidance. This gives the agent strong decision context.

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 explicitly discloses the read-only nature ('Pure read; no auth required'), states the return shape precisely, and lists the error case (NOT_FOUND). The only minor gap is not mentioning rate limits or idempotency behavior, but given no annotations exist and the tool is a simple read, 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?

The description is tightly structured with labeled sections (When to use, Behavior, Returns, Errors), each one to two sentences. Every sentence contributes value with zero waste. Format is scannable and front-loaded with the core purpose.

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-only fetch tool with two well-documented parameters and no output schema, the description covers all necessary context: purpose, safe/non-auth nature, exact return contract, and error behavior. Given the low complexity, nothing material 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 coverage is 100% and both parameters have descriptions in the schema. The description itself doesn't add parameter detail beyond what's in the schema, but the agent_token parameter has an alternative note in the schema (env var or header resolution). Baseline 3 is appropriate since the schema does the heavy lifting and the description confirms parameter usage context.

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

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

The description uses a specific verb+resource combination ('Fetch a registered task schema by id') with an explicit version reference (v2.10). It clearly distinguishes from sibling `register_task_schema` by focusing on the read side. The purpose is unambiguous.

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

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

The 'When to use' section provides a concrete scenario: an assignee about to complete a schema-gated task needs to read the required shape first. It states 'Pure read; no auth required,' which is an explicit exclusion/prerequisite clarification. This is model guidance for when to invoke this tool vs. not.

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 full responsibility and delivers: discloses cascade deletion of messages/tasks, documents idempotency (returns removed:false instead of error), details auth requirements (own token or manage_others capability), and enumerates error codes. Exceptionally thorough behavioral 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?

Well-structured with labeled sections (When to use, Behavior, Returns, Errors), front-loaded with the core action. Each sentence carries purpose. Slightly verbose around return semantics but all content is substantive, so it earns its length.

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 destructive mutation with no annotations and no output schema, this is model-complete: covers return format, error semantics, idempotency behavior, auth model, cascade effects, and when-not-to-use. No meaningful gaps remain for an agent deciding whether and how to invoke this 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%, so baseline is 3. The description adds value by explaining the semantics of the `removed` boolean return flag and clarifying that agent_token is optional (also resolvable from env var or header) — though this largely mirrors the schema. The auth/destruction context adds meaning beyond plain parameter definitions.

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?

Clear verb+resource: 'Remove an agent row so the relay reflects true presence after a clean shutdown.' Distinguishes from siblings (register_agent, set_status) by explicitly contrasting with set_status for offline announcements. The purpose is specific and action-oriented.

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 'When to use' section lists concrete scenarios (terminal exit, role rotation, recovery after revoke_token) and explicitly names the alternative tool (set_status with offline) for graceful working-state announcements. Offers strong when/when-not differentiation.

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 provided, so description carries full burden. Rich disclosure: role enforcement, heartbeat semantics (refreshes lease_renewed_at without changing status, prevented requeue), result required on complete/reject, webhook fires, auth requirements, error codes. Only minor gap is absence of explicit mutability/irreversibility notes, but the state-machine framing implicitly conveys this.

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?

Well structured with clear section labels (When to use, Behavior, Returns, Errors) and front-loaded purpose. Each sentence earns its place; the error list is comprehensive yet compact. Slightly longer than minimal but given the tool's complexity (5 actions, role matrix, webhooks, errors), the length is justified.

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?

Exceptionally complete for a state-machine tool with 5 parameters, no output schema, and no annotations. Covers every action's semantics, role restrictions, conditional return fields, error contract, and webhook side effects. No significant gaps for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value beyond schema: clarifies heartbeat behavior with lease_renewed_at, specifies result required on complete/reject, explains what each action transitions status to, and documents the complete return shape including conditional fields. This exceeds what the schema's brief param descriptions provide.

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?

Clear verb+resource ('Drive a task through its state machine, or extend its lease'). Distinguishes from siblings by explicitly stating read-only progress checks belong in get_task/get_tasks, differentiating from post_task (creation) and get_task/get_tasks (reads).

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?

Excellent when-to-use guidance: explicitly maps each action to the actor (assignee accepts/completes/rejects/heartbeats; requester cancels). Names get_task/get_tasks as the alternative for read-only checks. Also describes role-by-action enforcement, making when-not-to-use clear.

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