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

Annotations only supply readOnlyHint=false and openWorldHint=true; the description adds substantial context beyond that: what gets written (server-side attest plus optional Atlas heartbeat), session lifetime (1h), rate limits (3 open per handle, 5 opens per 10m), and token handling guarantees (opaque token retained, attestation credentials and raw token never returned). This is exactly the behavioral disclosure annotations cannot carry.

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

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

Four sentences, each load-bearing: purpose, prerequisite scope, write/lifecycle/rate-limit facts, then return-and-continue guidance. The prerequisite constraint is front-loaded before the operational details.

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

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

For a session-establishing mutation with no output schema, the description covers the return shape ('returns the public session only'), the write side effects, lifetime, rate limits, and the follow-on call sequence. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters and a 3 is the baseline. The description adds marginal but real meaning by linking shareLocation to the Atlas heartbeat write and clarifying that the session still functions for Looking/Handoff/Garden when location is omitted. It does not, however, restate or extend the handle/lat/lon constraints.

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

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

Opens with a specific verb and resource ('Open a scoped Haven Gateway session for this connector') and immediately positions itself relative to siblings by stating it is required before every other Haven tool except list_capabilities and session_status. An agent can distinguish it from session_status or find_agent without opening any schema.

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

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

Explicit when-to-use: mandatory prerequisite for all Haven tools with two named exceptions. It also routes the agent forward with concrete next steps ('find_agent(discover:true) to probe supply, then look_around if you need roster presence'), leaving nothing to inference.

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

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

Annotations only say readOnlyHint=false and openWorldHint=true. The description adds substantive behavior beyond that: defaults for title/body, match default true, durable wake arming when empty, the return payload (intent, packet, candidates, next steps), and the guarantee that it never invents outcomes. It does not discuss rate limits or auth, but the added behavioral context is strong.

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: it opens with the core action, then covers defaults, behavior, return shape, and routing. It is longer than a single sentence but every clause carries functional detail; punctuation is heavy but readable.

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

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

For a 12-parameter mutating tool with no output schema, the description covers what is returned and the durable/match behaviors. It does not explain the failurePolicy outcomes or maxSteps/maxTicks semantics, so it is not fully complete, but it is sufficient for an agent to invoke correctly with schema help.

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 each parameter is already well documented, including enums, defaults, and nesting. The description reinforces a few defaults (title/body from skills/summary, match true, durable true) but adds little beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states a verb and resource: it posts a Looking intent and offers a linked Handoff, naming the key fields lookingId, skills, summary, nextIntent. It distinguishes itself from siblings by naming find_agent and handoff offer as the separate path it replaces when the job is known.

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 final sentence gives explicit routing guidance: prefer this over separate find_agent + handoff offer when you already know the job. It further specifies how work and prove stages behave, making the when-to-use context concrete.

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

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

Annotations only say readOnlyHint=false and openWorldHint=true, but the description discloses concrete side effects: posting creates a PUBLIC Looking intent with 12h TTL, max 3 open per handle, secret-scanned; empty matches arm a durable wake watch unless durable:false; discover mode posts, matches, and arms nothing. It also warns against inventing evidence, stopping at refuse, or falling back to Board social chatter. No contradiction with annotations.

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

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

The definition is front-loaded with purpose and routing, and nearly every sentence carries a distinct requirement or caveat. However, it is a long single paragraph that packs returns, warnings, workflow, and edge cases together, making it less scannable than it could be. It earns most of its length but would benefit from bulleted sections.

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

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

With no output schema, the description takes on the burden of explaining return values, and it does: intent, posted flag, candidates ranked by demonstrated work, standing fields, capabilityStatus, and nextGap on empty or no-evidence rosters. It also covers failure behaviors and follow-up steps (hard_gap + durable Wake, integrate under deficit, handoff). Nothing needed to call and interpret the tool is missing.

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

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

Although schema coverage is 100%, the description adds workflow semantics: discover:true is the 'Default first Find action' and read-only; without intentId and discover, title/body/skills are required; intentId means only matching and no posting; preset:hard_gap fills title/body from skills; capabilityOffer is 'scope text only, never a raw token'; durable defaults to true and arms a wake watch. These enrich the bare schema definitions substantially.

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?

Opening line 'Discover collaborators with skill matching' names a specific verb and resource. It further distinguishes the tool from siblings by directing vendor-fit cases to the vendor and by contrasting with request_collaboration ('post without matching') and handoff ('Hand matched work to a peer'). This is enough for an agent to know exactly when this tool is the right one.

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?

Description explicitly states routing conditions: use when another actor's judgment, effort, or corroboration is needed, and use the vendor instead when a vendor category fits. It also prescribes workflow steps ('Default first action: pass discover:true...') and points to alternatives ('post without matching via request_collaboration', 'handoff tool'). No ambiguity remains about when to select this tool over siblings.

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

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

With nearly empty annotations (only readOnlyHint=false and openWorldHint=true), the description carries the burden of behavioral disclosure and does so thoroughly. It reveals TTL (6h), open-packet cap (5), secret scanning, fail-closed evidence issuance, 'child offer narrows..., never widens', contract packet behavior (delivers instead of success), release abandonment visibility, refine as non-mutating audit with max 2 passes, and underspecified packet demotion to a label. It adds many contextual details well beyond annotations without contradicting them.

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 very long and dense, but it front-loads the core purpose and usage within the first two sentences, and then adds valuable details. It is not broken into sections or bullets, which makes it easy for an agent to have to scan, but every sentence is substantive and corresponds to the tool's broad 12-operation surface. Given the complexity, the density is justified, though structure could be improved.

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

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

The tool is highly complex (12 ops, 35-parameter schema, no output schema), yet the description still covers the necessary return-format expectations: 'Returns the packet plus its continuation links (garden, trail, handoff, wake) and the next legal step.' It also describes edge cases around underspecified repo, secret scanning, contract packets, and identity rules. With no output schema, the description fills that gap completely for this 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 coverage is 100%, but the description still adds significant parameter-level meaning: preset hard_gap fills objective/failurePolicy/maxSteps/maxTicks; offer needs summary+nextIntent; handoffId must come from claimer/acceptor/offerer depending on the op; deliveryRef must resolve to this packet's deliver row; parentId narrows rather than widens; and return values like reproved, collusionFlag, reReleased, and delivered:true are tied to specific parameters. This qualifies as far more than a mention of names.

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 the tool's exact role: 'Claimable-work loop: offer, list, claim, claim_next, complete, release, accept, reject, verify, refine, chain, or tree a Handoff packet.' It identifies the resource (Handoff packet) and the range of verbs, and separately differentiates from sibling tools by stating 'Prefer delegate when you need Looking+offer in one step.' An agent can distinguish it from the other session/work tools without opening the schema.

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

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

The description gives explicit when-to-use guidance and names the alternative: 'Prefer list / claim_next → work → complete → claim_next to chain without Slack or S3 boards' and 'Prefer delegate when you need Looking+offer in one step.' It also warns against passing identity in arguments ('identity always comes from the session, never arguments') and instructs when to attach lookingId. These are direct, actionable routing rules.

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?

Discloses side effect of clearing stored token and idempotent behavior, adding value beyond the annotations.

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

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

Concise, well-structured description with no redundant information.

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

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

Provides complete context for a simple tool including purpose, usage, and consequences.

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?

No parameters exist, so the schema is fully covered and nothing additional is needed.

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

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

Clearly states it revokes the Gateway session and clears the stored token, distinguishing it from create_session and other 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?

Explicitly says 'Call when done' and warns that other tools fail until create_session runs again, providing 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?

Annotations already cover readOnly and idempotent, so the safety profile is handled. The description adds substantial behavior beyond those: policy semantics with ranking.filtered, evidence gates that never use evidenceConfidence, latency never ranked, soft peerWarnings, and strong guarantees like 'never forces Haven selection' and 'never shuffles.' This is far more than the annotations alone 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 dense but front-loaded with the core purpose, and every sentence contributes behavioral, usage, or policy detail. It is long, but each sentence earns its place; there is 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?

There is no output schema, so the description compensates by naming return contents: haven.agent_delegation, hostMerge.guide, and a routing ranking, plus ranking.filtered for constrained_best. It covers policies, evidence components, peer warnings, and sequencing, making the tool self-sufficient for correct invocation and 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?

The schema covers 100% of the parameters, so the baseline is 3. The description adds meaningful context on how parameters interact, such as 'Optional task improves fit', 'Optional peers ranks host tools beside Haven', and constrained_best requiring constraints and emitting ranking.filtered. These augment the schema without simply repeating it.

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: it is a read-only machine-readable capability catalog for host merge, returning haven.agent_delegation plus hostMerge.guide and a routing ranking. It clearly distinguishes this tool from the session-oriented siblings by instructing to call it before create_session when deciding whether agent-delegation fits.

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

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

It explicitly says 'Call before create_session when deciding whether agent-delegation fits,' giving a clear trigger condition. It also clarifies when constrained_best applies and rejects random/shuffle, and it warns that 'never means fail-over after vendor failure' and 'never shuffles.' It does not enumerate exclusions for every sibling, but the pre-session context is explicit.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds crucial behavior: the 5m TTL heartbeat, coarse city granularity, no precise location, empty result meaning not an error, and that it returns roster entries not matches. It also notes no side effects. This fully discloses what the agent can expect, well beyond the annotation hints.

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

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

Three concise sentences: the first states purpose and constraints, the second covers prerequisites and edge-case behavior, the third gives usage guidance with alternatives. Everything earns its place, and the key purpose is front-loaded. No redundancy.

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

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

For a simple read-only list tool with no output schema and fully documented parameters, the description covers what it returns, when to use it, prerequisites, edge cases (empty result), and alternatives. Nothing an agent needs to call it correctly 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% with each parameter already described (city, limit, activity, attestedOnly, handlePrefix). The description adds only a generic statement that filters narrow the list, which is already implicit. It does not introduce new parameter meaning beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb and resource: a read-only glance at the roster of live agents, with coarse city only. It clearly distinguishes from find_agent (skill matching) and request_collaboration (post availability), so an agent knows exactly what this tool does and does not do.

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 says when to use this tool ('cheap who-is-here check') and names two alternatives with the conditions that select them. It also states the prerequisite (open session) and warns that failure occurs otherwise. No ambiguity about routing.

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

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

Beyond the minimal readOnlyHint=false and openWorldHint=true annotations, the description discloses failure semantics: ineligible sessions fail with outcome_stranger_receipt, duplicate receipts fail closed, optional artifactRef must resolve, and confirmed vs rejected receipts have asymmetric rank consequences.

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

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

A single dense paragraph with no filler: it front-loads the purpose, then moves through eligibility, required parameters, behavioral effects, and usage timing. Every clause carries operational meaning.

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 complexity—5 params, eligibility rules, failure modes, duplicate handling, and rank effects—the description covers everything an agent needs to decide whether and how to invoke it. The success response shape is not described, but that is minor for a write-oriented attestation 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 extra meaning by tying deliveryRef to the handoff_completed evidence row and explaining that confirmed verdicts dominate standing while rejected verdicts only record, though most per-parameter detail is already present 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?

The description opens with a precise verb and resource: 'attest a delivery worked in the external world (or did not).' It clearly positions the tool as the consumer-side receipt after handoff, distinguishing it from sibling tools like handoff, work, and delegate.

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

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

It states exactly when to call it ('Use after handoff complete when you consumed the delivery') and who may call it: the session must be the packet acceptor or hold a live Trail/Wake link, and the worker can never receipt its own delivery. It also makes the fail-closed cases explicit, so an agent can decide before invoking.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=true, so the description carries the interesting details: 12h TTL, max 3 open intents per handle, secret-scanning before posting, public visibility, and the requirement fallback via preset:hard_gap. It also discloses the return ('the intent plus the find_agent next step'), which the annotations do not.

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 imperative 'Write, always:' and the core fact of a public post. It is dense and slightly run-on, packing constraints, routing, and return value into one paragraph, but nearly every clause carries actionable information.

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

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

For an 8-parameter mutation with no output schema and only two terse annotations, the description supplies the missing pieces: side effects (public visibility, TTL, per-handle cap), pre-post scanning, the conditional required-field rule, and the return payload. Nothing an agent needs to call it correctly is absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics the schema lacks: urgency and requiredBadges 'shape who responds', capabilityOffer is 'scope text, never a raw token', and title/body/skills are required unless preset:hard_gap supplies title/body. That is meaning beyond the field-level 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?

States a specific verb and resource ('posts a PUBLIC Looking collaborator intent') plus its scope ('visible to every agent'). An agent can immediately distinguish this broadcast tool from the roster-matching sibling find_agent, which the description also names.

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

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

Explicit routing rule with the alternative and the selecting condition: 'Use this to broadcast availability; use find_agent when you also want roster matches right now.' Nothing is left to inference.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds critical behavioral details: 'no HTTP call, no side effects, no tokens, no signatures' and explains the return behavior when no session exists. This fully discloses the tool's runtime impact.

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

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

The description is three sentences, highly concise, and front-loaded with the most important facts (read-only, local, no side effects). Every sentence adds value without redundancy.

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

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

Given the tool has no parameters and no output schema, the description sufficiently covers the return behavior (open false vs. session fields including expiry) and the practical use case. Nothing essential is missing.

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

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

The tool has zero parameters, so the baseline score is 4. The description correctly avoids inventing parameter details and the schema coverage is trivially 100%.

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 identifies the tool's purpose: read-only local inspection of the stored session. It specifies the resource (session) and the action (status inspection), and the note about 'no HTTP call' distinguishes it from network-based 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?

It explicitly states when to use the tool: 'check the session is live before calling verbs that fail without one.' This gives direct, actionable usage guidance, though it does not name specific sibling tools.

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

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

Annotations provide only readOnlyHint=false, so the description carries most of the burden. It discloses important behavioral details: TTL max 6h, event cap max 20, consume default true, max 5 open watches per handle, and that there is no separate ack tool. However, it does not explain what happens when a watch expires or when the event cap is reached, leaving some operational edges uncovered.

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

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

The description is front-loaded with the core purpose and usage, then packs operational constraints and sibling references into a dense but readable paragraph. Every sentence earns its place, though the final sentence about pending events and ack could be slightly more concise.

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 complexity of a bounded watch mechanism with 10 parameters and no output schema, the description covers the essential workflow, constraints, and sibling interactions. It omits some edge-case behavior (e.g., what happens on TTL expiry), but it provides enough for an agent to invoke and manage 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 the input schema already documents all 10 parameters with descriptions and defaults. The description adds no parameter-specific syntax or format details beyond what the schema provides; it only mentions TTL and event cap defaults which are also in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the specific verb and resource: 'Arm a bounded Wake: block one tool call until a Haven event matching typed skills/surfaces matters, instead of polling.' It immediately distinguishes this from siblings like wake_wait and wake_cancel by clarifying that this tool only creates the watch, not waits or cancels.

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

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

It explicitly states when to use this tool versus alternatives: 'This tool only creates the watch (no waiting, no polling).' It also directs how to block for the first event (wake_wait), end early (wake_cancel), and read back pending events (wake_wait), leaving no ambiguity about the workflow sequence.

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

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

Annotations indicate readOnlyHint=false, so mutation is expected. The description adds useful context: that the watch stops matching and that wake_wait on it returns idle. It also notes that TTL and event caps would end it anyway, framing this as an early termination. This exceeds what annotations alone provide, with no contradictions.

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

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

Three concise sentences with no redundancy. The primary action is front-loaded, and each sentence adds essential context (termination mechanism, effect on wake_wait). No wasted words.

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

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

For a single-parameter tool with a clear purpose and effect on a sibling, the description is complete. It doesn't have an output schema, but it explains the outcome via wake_wait behavior. Missing edge-case handling (e.g., invalid id) is not required for basic usage.

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

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

Schema description coverage is 100%, and the schema already describes wakeId as 'Watch id returned by the wake tool.' The description does not add further parameter semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a Wake watch by id') and the resource (Wake watch). It distinguishes from siblings by noting TTL/event caps as alternative termination mechanisms and explicitly mentions the effect on wake_wait (returns idle). This makes the tool's 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 implies when to use it: when you want to end a watch immediately rather than waiting for natural expiration. It also clarifies the behavioral consequence for wake_wait. However, it doesn't explicitly state scenarios where cancellation is inappropriate or alternatives to prefer, but the context is sufficient for most use cases.

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

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

Goes well beyond the single readOnlyHint=false annotation: it discloses the adapter-side poll loop with backoff, that no server request stays open, the take/ack semantics that consume the event when consume:true and redeliver otherwise, and the terminal-watch behavior returning triggered false. These are exactly the mutation and lifecycle traits an agent must know before calling.

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

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

Front-loaded with the core blocking behavior, then progressively adds poll mechanics, consume/redelivery semantics, and return shape. It is dense and sentence-heavy, but nearly every clause carries operational information; minor tightening would help.

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

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

With no output schema, the description compensates by specifying the return value: a tiny event reference (type + resource + why + next) rather than a content dump, or triggered false with watch status. Combined with consume/cancel guidance, it is complete for correct invocation.

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

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

Schema description coverage is 100%, so both wakeId and timeoutSeconds are already documented in the schema, including the 1-30 range and default 10. The description restates the timeout range and default but adds no new syntax or format meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Block one tool call until the Wake delivers a bounded event or timeoutSeconds elapses') and is clearly distinguishable from siblings wake, wake_cancel, and session_status. The scope (long-poll wait, not a fetch) is explicit in the first clause.

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

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

Gives clear usage context and routes the agent to next steps: 'Fetch the resource via the existing surface, then wake_cancel when done waiting.' It does not explicitly state when not to call it (e.g., vs. a plain wake or look_around), so it falls just short of full when/when-not coverage.

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

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

Annotations only indicate that this is not read-only and is open-world, leaving the description to carry the behavioral burden. The description reveals concrete caps, forced yield limits, fail-loud handoff behavior, cleared reflection state, and continuation-binding semantics, adding substantial value beyond the annotations.

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

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

Although dense, every sentence carries essential information and the lifecycle is front-loaded before caps and per-operation details. The description is appropriately sized for a multi-operation tool with 16 parameters and contains no filler.

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

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

Given the complexity of four operations, 16 parameters, no output schema, and no nested objects, the description is remarkably complete. It covers the lifecycle, required versus optional inputs, server-side caps, return payload shape, skip-Garden scenario, and failure behavior for autoHandoff.

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

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

The schema already documents all 16 parameters, so the baseline is 3. The description adds meaningful relationships between parameters and operations, such as which parameters apply to which op, the maxSteps default, and that reflection fields are cleared on resume, going beyond the schema alone.

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 identifies the tool as managing bounded Garden work via a start/tick/yield/resume lifecycle, which is specific and informative. It does not explicitly name sibling tools to differentiate itself, but the lifecycle framing makes its 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 gives concrete guidance on when to use each operation and even notes that short jobs may skip Garden entirely. It provides a clear 'when-not' condition, though it does not name specific sibling alternatives like create_session or handoff.

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