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

Annotations already declare readOnly=false, idempotent=false, destructive=false, openWorld=false, so the safety profile is covered. The description adds real context beyond that: the manifest is persistent, it grants 'automatic scoped reading instructions', and it explicitly does not spawn workers, which clarifies the side-effect boundary of a non-read-only tool.

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

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

Two short sentences plus a one-line caveat, all front-loaded with the core action first, then integration, then the side-effect boundary. Zero filler.

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

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

An output schema exists, so return values need no explanation, and the 100% schema coverage handles parameters. The description covers purpose, integration path, and side-effect scope, leaving only the create-vs-sibling relationship unstated.

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

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

Schema description coverage is 100%, so entries (1..32 unique descriptors), task_id, and ttl_seconds are already fully documented in the schema. The description adds no syntax, format, or constraint detail beyond it, 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+resource (pin immutable artifact versions in a persistent task manifest) and adds a scope caveat ('This does not spawn workers') that helps distinguish it from worker-spawning siblings. It does not explicitly name artifact_manifest_get/verify/release, but the create/pin framing is clear enough to route correctly.

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

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

Provides a downstream usage instruction (pass the returned manifest to get_subagent_context.artifact_manifest) and a negative condition ('does not spawn workers'), but gives no when-to-use guidance versus sibling tools like artifact_manifest_get, artifact_manifest_verify, or artifact_publish. Usage is implied rather than 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context: the workspace scope and the boundary that it does not read manifest bodies. It does not mention auth or rate limits, but with annotations this is above adequate.

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 sentence front-loads the verb and resource, then appends the key scope exclusion. There is no wasted verbiage.

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 a simple two-parameter read with an output schema, so return values need not be explained. Parameters are fully documented in the schema, annotations cover idempotency and read-only behavior, and the description states workspace scope and the no-bodies constraint. Nothing needed for correct invocation 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 (manifest_id, manifest_sha256) have their own schema descriptions, including the warning to never substitute latest. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 is correct.

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

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

States a specific verb (Read) and resource (pinned active manifest in this workspace), and adds a scope exclusion (without reading its bodies) that implicitly distinguishes it from artifact_read. However, it does not name or explicitly contrast itself with sibling tools like artifact_manifest_verify or artifact_read, so a 4 is appropriate.

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 phrasing implies when to use it (to get manifest metadata without body content), but offers no explicit when-to-use/when-not guidance or named alternatives. An agent must infer that artifact_read is for bodies and verify is for validation.

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

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

Annotations already declare idempotentHint=true and destructiveHint=true, so the bar is lower, yet the description adds genuine nuance: it discloses that revocation is partial ('Already read text cannot be removed from a worker's memory') and that immutable artifacts are retained. This is exactly the kind of beyond-annotation context that helps an agent predict side effects.

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 action and its idempotent nature are front-loaded in the first sentence, with the behavioral caveat and retry guidance following. It's efficiently sized with little waste, though the trailing sentence is slightly loosely connected to the action.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description completes the picture with the retention/irreversibility nuance and retry intent; only error conditions (e.g., SHA mismatch) are left unaddressed, which keeps it from a 5.

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 manifest_id and manifest_sha256 are already documented as the pinned identifier and exact SHA256. The description adds no further syntax or format detail, so the baseline 3 applies.

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

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

The description opens with a specific verb+resource: 'Revoke a manifest idempotently,' which an agent can distinguish from siblings like artifact_manifest_create, _get, and _verify. It's clear what the tool does, though it doesn't explicitly name the sibling tools it should be chosen over.

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?

'Discard pending output under a revoked manifest and prepare a new authorized attempt' implies the usage context (cleaning up a failed/stale manifest before retrying). However, it gives no explicit when-not conditions or comparison against alternatives such as artifact_manifest_verify or local_context_revoke, leaving the agent to infer selection.

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

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

Annotations already declare readOnly, idempotent, and closed-world. The description adds genuine value beyond that: the 'independently recheck' framing signals a re-verification pass, and the caveat that 'Hash integrity does not prove findings are correct or tests ran' scopes what a passing result actually guarantees.

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

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

Three tight sentences, front-loaded with the core action, then the pairing instruction, then the limitation. Every sentence carries distinct information with no filler.

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

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

An output schema exists and annotations cover the safety profile, so the description need not explain returns or read-only behavior. It covers purpose, when to use, and the key limitation, though it could say more about what a failed verification means for the caller.

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

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

Schema description coverage is 100%, with both required fields (manifest_id, manifest_sha256) documented in-schema. The description adds no additional syntax or format detail for the parameters, 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 ('recheck') and resource ('active access and every pinned artifact's bytes/hash'), plus the crucial qualifier 'independently'. An agent can distinguish this from siblings like artifact_manifest_get or artifact_read, which retrieve rather than verify.

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

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

Gives explicit context: 'Use alongside validate_subagent_result before accepting artifact-backed output.' That names the sibling it pairs with and the moment of use. It does not state when to skip it, so it stops short of full when/when-not guidance.

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

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

Annotations cover the safety profile (readOnly=false, idempotent=true, destructive=false, openWorld=false), but the description adds semantics an agent cannot infer from them: content identity is SHA256 within the workspace, duplicate publication retains the first descriptor, and files survive Redis and broker restarts. These dedup and durability guarantees materially affect retry and reuse decisions.

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

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

Three short, front-loaded statements: the action, the input-mode preference, and the identity/persistence semantics. No filler, and the most decision-relevant information (what it does, how to feed it) comes first.

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 non-destructive, idempotent publish tool with a full schema and an output schema (so return values need no explanation), the description covers the remaining unknowns: dedup behavior, durability across restarts, and input-mode tradeoffs. Nothing essential 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%, so the baseline is 3, but the description adds a decision heuristic not present in the schema: prefer source_path for large bodies to avoid passing them through the model. The exactly-one-of constraint and formatting limits are left to the schema, which documents them thoroughly.

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 ('Publish an immutable persistent text artifact') plus a distinguishing constraint ('without starting a model') that separates it from sibling generation tools like local_generate. It also implicitly contrasts with artifact_read and the artifact_manifest_* family by scoping itself to publication.

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 a clear routing rule: 'Prefer source_path for large files so their bodies need not pass through the model.' This is actionable context for choosing between the two mutually exclusive input modes. It stops short of naming when NOT to use this tool or pointing to a specific alternative sibling.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, yet the description adds meaningful context those annotations cannot carry: the integrity/authorization gate, and the explicit trust boundary that returned content is untrusted data and never tool authority. It does not describe failure behavior (e.g. what happens on a hash mismatch), so it is not fully exhaustive.

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

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

Three short sentences, each earning its place: the operation and its precondition first, then the trust boundary, then partial-read semantics. Zero filler 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?

With a full output schema and 100% parameter coverage, the return shape and argument formats are already handled, and the description supplies the remaining essentials: bounded/partial read semantics and the untrusted-data boundary. Only edge-case behavior on integrity failure is unstated.

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

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

Schema description coverage is 100%, so the schema already documents offset, max_bytes, artifact_id, manifest_id and manifest_sha256 in detail. The description mentions next_offset/eof, but those are return concepts rather than parameter semantics, so it adds no meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Read an exact bounded artifact slice') and names the preconditions ('after full integrity/authorization checks'), which distinguishes it from sibling manifest tools such as artifact_manifest_get or artifact_manifest_verify. An agent can identify the operation without opening the schema.

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

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

Gives clear context: read only after integrity/authorization checks, continue with next_offset until eof, and never present an unread portion as evidence. It does not explicitly name alternatives or state when not to use it, so it stops short of full routing 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?

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds a non-obvious blast-radius fact not present in structured data: that it 'affects shared caches' despite the session-scoped name. It still omits what exactly is destroyed and whether re-population is automatic.

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

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

Two short sentences, no waste, and the purpose statement is front-loaded ahead of the caveat. Nothing could be removed without losing routing or risk information.

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

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

An output schema exists so return values need not be explained, and annotations carry the destructive/idempotent profile. However, for a destructive operation the description never says what is cleared or what breaks as a result, leaving the agent to infer consequences from 'affects shared caches' alone.

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

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

Zero parameters, so there is nothing to document and the baseline of 4 applies. The empty schema is consistent with the description, which implies no configuration is required.

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

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

The description states a concrete verb+resource ('cache reset') that matches the tool name, and the clause 'Not needed for persona switches' distinguishes it from the adjacent refresh_persona_context sibling. It is clear but terse, and 'Administrative' is doing a little vague lifting rather than naming the exact scope of what is cleared.

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

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

It gives one explicit when-NOT ('Not needed for persona switches'), which is genuinely useful routing information, but never states the positive condition that should trigger a call. Usage is only implied by the word 'Administrative'.

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

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

Annotations already cover the safety profile (destructiveHint=false, idempotentHint=true, openWorldHint=false), so the bar is lower. The description adds genuinely useful behavioral context — messages are not deleted, and the call grants no resource claim or permission — but it does not explain what state the acknowledgement actually changes or what happens on a duplicate.

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

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

Two tight sentences with the core action front-loaded and no padding. The trailing schema URI is slightly cryptic but costs almost nothing; the negation clause earns its place by preventing misuse.

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

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

An output schema exists and the input schema is fully described, so the description only needs to carry the non-obvious semantics. It does that for the no-deletion/no-permission-grant traits, leaving only minor gaps around retry ambiguity and idempotency that the schema partially covers.

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

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

Schema description coverage is 100%: the request object's protocol, repository_id, participant_id, capability, operation_id, message_ids limits, retry semantics and size/depth bounds are all documented in the schema. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('Record delivery processing for private inbox messages') and clarifies the scope by negation — it does not consume an agreement, artifact or task. That contrast helps separate it from mutation-style siblings like cooperation_apply, though no sibling is named directly.

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

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

Usage is implied rather than stated: the agent can infer it should be used to acknowledge receipt of a delivery, and the 'does not accept an agreement, artifact or task' clause implicitly routes those cases elsewhere. However, there is no explicit when-to-use/when-not-to-use guidance or named alternative tool.

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

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

Adds substantial non-obvious behavior beyond the annotations: claims only coordinate clients and do not fence shell writes, an expired heartbeat never grants ownership, scope/host-user authorization is mandatory, and capability loss has no online reset. These are real operational constraints not derivable from the annotation block. It is dense jargon, but it meaningfully extends the safety profile already given by idempotent/destructive 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?

Front-loads the core purpose in sentence one, which is good. But the remaining five terse, jargon-heavy clauses ('An expired heartbeat never grants ownership', 'Independent-root capability loss has no online reset') are cryptic and some are tangential to the invocation decision, so the density is not fully earned.

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

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

An output schema exists so return values need not be explained, and annotations cover the safety profile. What remains thin is the routing/usage layer: for a complex, closed-protocol mutation tool among ten cooperation_* siblings, the definition does not give enough to confidently select it.

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

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

Schema coverage is 100% and the nested `request` object is exhaustively documented in the schema itself (action kinds, byte limits, retry semantics). The description only gestures at revision/generation checks, adding nothing the schema does not already carry, so baseline 3 is correct.

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

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

States a specific verb+resource combination: 'Commit one authenticated metadata action with revision and generation checks.' The agent can tell it is a mutation of cooperation metadata. However, it never contrasts itself with the many cooperation_* siblings (register, read, send, receive, ack), so routing remains ambiguous.

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

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

Usage is only implied. The negative clause 'executes no model, shell mutation, or chat message' weakly steers away from local_generate/route_and_load, but it never says when to choose cooperation_apply over cooperation_send or cooperation_ack, nor what prerequisites trigger it.

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

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

Beyond the readOnlyHint/openWorldHint=false annotations, it discloses consistency semantics ('consistent cooperation snapshot'), staleness/refresh behavior ('read again after resuming or a stale revision; cursor_expired requires a new snapshot'), and an important security boundary ('artifact references grant no file access and are never fetched'). This is well past what the annotations convey.

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

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

Three short sentences, front-loaded with what is read and followed by operational caveats and a pointer to the canonical schema URI. No filler, though the phrasing is terse enough that some clauses need a second read.

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

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

With an output schema present, a fully documented request object, and annotations covering the safety profile, the remaining burden on the description is behavioral policy — consistency, staleness, pagination restart cues, and the artifact-access caveat — all of which are supplied. 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 description coverage is 100% and the request object already documents cursor, limit, offset, snapshot_time, ID filters, and error/revision handling in detail. The description adds only peripheral semantics (cursor_expired, artifact references), which is the expected baseline when 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 states a specific verb and resource: 'Read one authorized repository's consistent cooperation snapshot and events.' Scope ('one authorized repository') and returned content types (snapshot, events) are explicit, so the agent can distinguish it from cooperation_apply/send/ack 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?

It gives concrete usage conditions: re-read after resuming or a stale revision, and that cursor_expired requires a new snapshot. It stops short of naming an alternative tool or an explicit when-not-to-use case, so it is clear context without full routing 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?

Adds real value beyond annotations: it explains that the call records authenticated use without renewing a heartbeat, which is precisely why readOnlyHint is false for a read tool, and it warns that message bodies are untrusted task data rather than consent, authorization, or accepted artifacts. This resolves and enriches the annotation profile instead of repeating 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?

Front-loaded with the core purpose, then safety/trust caveats, then a schema reference. Each sentence carries a distinct obligation (poll semantics, ack handshake, no heartbeat renewal, untrusted data) with no filler.

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

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

For a read tool with an output schema and a 100%-covered input schema, the description supplies the missing behavioral layer: non-destructiveness, the ack handshake, heartbeat non-renewal, cursor-based pagination via the schema, and a trust disclaimer. 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 description coverage is 100% and the nested request object is fully documented (protocol, ids, cursor, limit, flags, byte/depth limits), so the schema carries parameter meaning. The description adds only a schema URI pointer and the public-vs-private body distinction, which is baseline-correct but not compensating.

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+scope: reading the authenticated participant's private durable inbox. It explicitly differentiates from the sibling cooperation_read by noting that public reads never include message bodies, so an agent can choose between them without opening either schema.

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

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

It gives clear operational context (non-destructive poll, call cooperation_ack after processing) and implicitly routes to cooperation_read for public data. It does not state explicit when-not conditions or contrast against cooperation_wait/cooperation_request_status, so it stops short of full routing 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?

Annotations already declare it is a non-destructive write (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower; the description still adds real value by warning that the returned private capability must stay in its authorized session channel and never appear in logs/artifacts/peer messages, and by clarifying it only observes Git identities and records metadata. It does not disclose failure or rate behavior, keeping it short of a 5.

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

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

The purpose is front-loaded in the first sentence, followed by a safety constraint, a scope statement, a prerequisite and a mode rule, each in its own sentence with no filler. Nothing is redundant with the schema.

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

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

For a complex mutation tool with a nested request object and an output schema, the description covers the prerequisite, the fallback mode, the side-effect boundary and the sensitivity of the returned capability, so an agent can invoke it correctly. The pointer to agents-core://cooperation/schema for full contracts is a sensible hand-off.

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 the request object, its required fields, the 1..50 resource scope and the size/depth limits. The description adds only the parent_relay fallback nuance, which the schema already lists as a communication_mode/execution_mode value, 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: registering an execution in the cooperation journal, and explicitly distinguishes itself from siblings by denying spawning, editing and message-sending. The phrasing is jargon-heavy ('optional installation daemon's cooperation journal'), which slightly obscures the mental model, but an agent can still tell it apart from cooperation_send/cooperation_apply.

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

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

It gives a prerequisite ('Owner registration must already permit the physical checkout') and a mode-selection rule ('Parent-relay mode is the fallback when the host has no safe independent capability channel'), plus implicit differentiation via the 'does not spawn, edit or send' clause. However, it never explicitly says when to choose this tool over cooperation_apply or cooperation_read.

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

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

Adds real semantic context beyond the annotations: a completed request 'does not validate work, accept an artifact or grant consent', and deadline expiry 'changes metadata only, never stops execution'. This explains the semantics that would otherwise be misread from a 'completed' or 'expired' state. It does not, however, explain the unusual readOnlyHint=false (the implicit metadata materialization) in so many words.

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

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

Front-loads the core purpose in the first sentence, then layers the two important caveats and the schema pointer. Nothing is wasted, though the trailing 'Schema: agents-core://cooperation/schema' line is slightly dangling.

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

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

An output schema exists, so return values need no explanation, and the description supplies the needed semantic caveats plus a schema reference for an object with nested fields. Adequate for a status-read tool; only the absence of sibling routing keeps it from a 5.

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 both the request object and workspace. The description adds little parameter detail, only pointing at an external schema URI ('agents-core://cooperation/schema'), which is a useful pointer but not added semantic depth. Baseline 3 applies.

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

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

States a specific verb ('Read') and resource ('one private request's current delivery and declared processing outcome'), clearly distinguishing this status-read from the mutating sibling cooperation_request_update. It does not explicitly name the sibling alternatives (cooperation_read, cooperation_wait), so it stops short of a 5.

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

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

Usage is implied by the resource ('one private request's status'), and the schema notes only the sender or recipient may inspect it, but the description gives no explicit when-to-use versus cooperation_read, cooperation_receive or cooperation_wait. No exclusions or routing guidance are provided.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the schema documents retry/revision semantics in depth. The description adds modest context: per-request revisioning, durable receipt, and the explicit disclaimer that receipt/consent/cancellation/acceptance are separate concerns and that a prepared worker contract is never altered. That is useful scope clarification but no new operational behavior beyond 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?

It is short at three sentences/fragments, but the leading sentence is obscure and the second sentence enumerates concepts without explaining the tool's action. Space is spent on abstractions rather than front-loading the concrete 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?

With a present output schema, full annotation coverage, and a fully documented parameter schema, the description need not explain returns or params. However, it omits the primary usage context (when to record a state transition versus reading or sending), leaving a noticeable gap for a mutation tool surrounded by similar siblings.

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

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

Schema description coverage is 100% and the nested 'request' schema is exhaustively documented (state machine, terminal immutability, required reason fields, byte limits). The description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

The name/title says 'Update cooperation request status', but the description reframes it as 'Record processing metadata with a per-request revision and durable receipt', which is abstract jargon rather than a concrete verb+resource. It states a scope boundary ('never changes a prepared worker contract') but never distinguishes itself from siblings like cooperation_request_status, cooperation_send, or cooperation_ack.

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

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

There is no explicit when-to-use guidance and no alternative named among the many cooperation_* siblings. The only routing signal is a negative one ('This tool never changes a prepared worker contract'), which tells the agent what the tool is not rather than when to call it.

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

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

Goes well beyond the annotations by disclosing auth requirements, the security posture of the payload (untrusted task data, grants no consent/claim/permission, never include capabilities or secrets), and retry/idempotency semantics. The annotations cover safety profile, but the description adds the operational and security context an agent actually needs.

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

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

Front-loads the core action in the first sentence, then layers authorization, scope limits, security warnings and a schema pointer in short, dense sentences. Every sentence earns its place, though the terse trailing 'Schema:' line is slightly abrupt.

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 complex, security-sensitive write tool with a nested request object and an output schema, the description covers authorization, delivery semantics, idempotent retry, prohibitions, and scope limits. Since an output schema exists, return values need not be explained, and 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 description coverage is 100% and the nested request object is exhaustively documented in the schema itself, so the description only points at 'agents-core://cooperation/schema'. It adds no further field-level meaning, which is the baseline-3 case when structured fields carry 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?

States a specific verb (persist/send) and resource (private message to a registered participant's daemon mailbox), with the scope 'private' and 'daemon mailbox' clarifying it isn't an external chat. It clearly separates itself from siblings like cooperation_wait and cooperation_read by describing itself as the write side.

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

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

Gives an explicit authorization precondition (only the sender's authenticated execution or an authorized immediate parent relay) and an explicit when-not (does not wake a model or message an external chat). It references cooperation_wait as the recipient-side counterpart but doesn't systematically route the agent between the other cooperation_* 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?

Beyond the annotations (idempotent, non-destructive, non-open-world), the description adds real behavioral context: the wait is asynchronous and cancellable, it is non-consuming, it does not renew claims or heartbeats, and it will not start an idle host model. That is material for an agent deciding whether to block on this call. There is mild tension between 'non-consuming' and readOnlyHint=false, but 'completes an active call' plausibly explains the non-read-only hint, so this is not an outright contradiction.

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

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

Four short sentences, front-loaded with the action and then the operational caveats; each sentence carries distinct information (cancellability, cursor resumption, host-wake limitation). Slightly cryptic phrasing in the first sentence costs it a point, but there is no filler.

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

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

An output schema exists, so return values (next_cursor, has_more, timed_out, service_epoch) need not be described here, and the rich schema covers inputs. The description supplies the blocking/wait semantics an agent needs. The remaining gap is sibling differentiation, which limits it to a 4 rather than a 5.

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 nested request object already documents protocol, repository_id, participant_id, capability, subject_id, after_cursor, limit, timeout_seconds, and the byte/size limits. The description adds no parameter-level meaning of its own, so the baseline of 3 applies.

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

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

The opening sentence names a recognizable action (long-poll wait for private notification events bounded by a timeout), but 'Complete an active call when private events arrive' is jargon-heavy and reads oddly for a wait primitive. It never distinguishes itself from close siblings like cooperation_receive, cooperation_read, or cooperation_request_status, so an agent cannot route between them from the description alone.

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

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

The description implies usage through operational constraints ('Resume from the durable cursor after reconnect', 'zero polls' semantics via the schema, and the explicit note that it never wakes an idle host model). However, it gives no explicit when-to-use/when-not versus the other cooperation_* tools, leaving selection 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?

Goes beyond the annotations (destructiveHint=true, idempotentHint=true) by disclosing that the text remains in history and that removing a local copy of a built-in restores the built-in. It omits any mention of the expected_revision concurrency guard or permission requirements, which matters for a destructive operation.

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

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

Two tight sentences with the core action and precondition front-loaded and no filler. The inline "(user:/repo:)" fragment is slightly cryptic without surrounding explanation, and the second sentence is somewhat tangential to the primary action.

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

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

An output schema exists so return values need not be explained, and annotations already cover the safety profile. However, for a destructive operation the description leaves the required expected_revision argument unexplained and does not clarify reversibility beyond "stays in history," so it is only adequate.

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

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

Schema description coverage is only 33% (only workspace is documented). The description partially compensates by revealing the flow identifier format (user:/repo:), but the required expected_revision parameter is never explained in either the schema or the description, leaving a mandatory argument opaque on a delete.

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 (Delete) plus resource (personal flow) and scopes it with the identifier prefixes (user:/repo:), immediately routing the agent away from get_flow/list_flows/save_flow. The built-in-shadowing sentence further distinguishes personal-flow deletion from any built-in semantics.

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?

"on explicit request" gives a clear precondition for invoking a destructive tool, and the built-in sentence explains a consequence-driven case for deletion. It does not name an alternative (e.g. save_flow to overwrite) or state when not to use it, so it stops short of explicit alternative 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds genuinely new behavior: removal is irreversible locally, cached versions are destroyed alongside the subscription, and the source document/built-in rules are preserved. The recovery path via re-subscription is information the annotations cannot convey.

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

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

The core action is front-loaded, followed by two short sentences scoping what is untouched and what is unrecoverable. No filler, though the phrasing 'a requested subscription' is slightly vague and could be tightened.

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

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

An output schema exists so return values need no explanation, and annotations cover the safety profile. The description successfully rounds out the irreversible-delete semantics; only the undocumented parameters remain a gap.

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

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

Schema description coverage is 0%, so the description carries the burden. 'Using its current revision' hints that expected_revision is an optimistic-concurrency guard, but neither parameter is named or explained in terms of format or failure behavior, leaving rule_id entirely unilluminated.

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 (remove) plus resource (subscription) and scope (its cached versions), and explicitly bounds what is untouched (source document, built-in rules). It separates itself from the sibling family by clarifying it removes rather than edits or rolls back, though it never names the adjacent tools directly.

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

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

Offers an implicit recovery route ('subscribe to its URL again to reconnect it'), which points at subscribe_user_rule, and warns that there is no local rollback. However it never explicitly states when to prefer this over rollback_user_rule or set_user_rule_enabled, so the routing guidance is only implied.

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

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

Beyond readOnlyHint=true and openWorldHint=false, the description discloses the key non-obvious traits: nothing is written on needs_summary, the refusal policy for protected installation/source roots, the error shape including pid/workspace_inputs/hint over stdio, and the fact that workspace_id/repo_path/repo_hash must be passed unchanged to the write tool. That is materially more than the annotations convey.

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

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

It is front-loaded with the read-only guarantee and the write split, and the status-based return shapes are laid out in a scannable list. It is longer than necessary, however, and since an output schema already exists, enumerating individual return fields duplicates structured data.

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 moderate-complexity tool with 3 optional params, no required params, an output schema, and a readOnly annotation, the description covers the important behaviors: read vs write separation, protected-root refusal, and status-dependent outcomes. The only real gap is the undocumented force_refresh parameter.

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 67%: repo_path and workspace are documented in the schema, but force_refresh has no description anywhere and the tool description never explains it (it only alludes to refresh being required via status). The mention of workspace_id and repo_hash refers to a different tool's parameters, so it adds no meaning for this tool's inputs. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Read-only repository description') and immediately distinguishes itself from the sibling write_repo_summary ('Persistence is a separate explicit write_repo_summary call'). It also clarifies the two possible outputs (cached summary preview vs deterministic context bundle), so an agent can tell what it gets back. It stops short of a crisp one-line statement of 'describe this repo's current summary state', but 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?

It gives clear routing guidance: read here, persist only via the separate write_repo_summary call, and for protected installation/source roots keep the overview in the answer or use a separate worktree. It also instructs the caller to follow the returned instruction before persisting. It doesn't spell out when describe_repo itself should be preferred over other context tools in the sibling set, but for the read/write split it 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?

Annotations (readOnlyHint=false, idempotentHint=false) already signal a stateful activation, and the description reinforces this by disclosing the NO_CHANGE path, the force_reload recovery path, and the replaces_activation_id guard for applying a returned descriptor. That is real behavioral context beyond the annotations, though auth/permission requirements and side effects on the prior persona are not covered.

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

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

Front-loaded with the core action, then layered protocol rules in short sentences with no filler. It is dense with domain jargon (ROUTE_REQUIRED, NO_CHANGE, replaces_activation_id) that is not defined, but every sentence carries operational weight.

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

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

An output schema exists, so return shape need not be explained, yet the description still covers the SUCCESS/descriptor application rule and NO_CHANGE semantics. For a 7-parameter, nested-object activation tool it is nearly complete, missing only failure/error handling and permission context.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters, including current_persona's verbatim-copy requirement and force_reload. The description restates protocol_version=2 and current_persona rather than adding syntax or format meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (load an agent/persona) and names the trigger condition (explicitly chosen agent or ROUTE_REQUIRED selection). It also distinguishes itself from refresh_persona_context, which handles refreshing the same role's skills. It does not, however, differentiate itself from route_and_load or get_subagent_context in the sibling set, leaving some 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?

Gives concrete usage conditions: pass protocol_version=2 and current_persona, expect NO_CHANGE for the same active agent, use force_reload=True to restore lost instructions, and route to refresh_persona_context for skill refresh. This is clear context with one explicit alternative, but it stops short of stating when NOT to use this tool versus route_and_load.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, yet the description adds genuinely new behavioral context: the flow.sync_conflicts field indicating an unmergeable library sync, and the rule that for a local copy of a built-in the upstream value holds the current text. That is real operational guidance beyond the safety 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?

Four short, front-loaded chunks with no filler: purpose first, then per-parameter semantics, then the sync_conflicts warning. The built-in/upstream sentence is slightly cryptic in isolation but short enough not to hurt.

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

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

An output schema exists, so return values need not be explained in depth, yet the description still covers flow ID forms, version semantics, restore behavior, and the sync_conflicts signal. The only gap is that the workspace parameter goes unmentioned in prose, which its schema description reasonably covers.

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

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

Schema coverage is 67% and the required 'flow' parameter is undocumented in the schema, so the description has to compensate — and it does, spelling out the bare-ID vs builtin:/user:/repo: forms. 'version' is described as a history entry used to view or restore older text, mapping it to the restore path via save_flow. Only 'workspace' is left to 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?

States a specific verb and resource ('Read a flow') and enumerates what it returns (Markdown, revision, saved versions), which distinguishes it from list_flows, save_flow, and run_flow. The 'before editing it' framing further pins its role in the workflow.

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

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

Gives clear when-to-use context ('before editing it') and explicitly routes the restore case to save_flow with the retrieved content. It does not, however, state when not to use it versus siblings like list_flows or describe_repo, so it falls short of full alternative 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?

readOnlyHint=true already establishes the safe-read profile, so the bar is lower; the description still adds substantial non-obvious behavior: unknown arguments are rejected, a 48000-character total request cap, endpoint failure does not authorize bypass, and insufficient context returns an error with no partial package. It does not describe rate limits or idempotency across attempt_id values, so it is strong but not exhaustive.

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

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

Front-loaded with purpose and the no-spawn negation, then the constraints and the required follow-up call. Dense but every sentence carries an operative rule. It is slightly long and some clauses are run-on, which keeps it out of the top band.

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

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

For a 13-parameter tool with nested objects and a declared output schema, the description covers the workflow, error semantics, and budget limits, and correctly leaves return-envelope details to the output schema. It leaves the meaning of retained 'contract' and the interplay of attempt_id/artifact_manifest lightly specified, but nothing critical to a correct call 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 baseline is 3. The description adds a constraint the schema does not carry: a 48000 canonical-JSON-character total including unknown fields, which bounds the combined task/context/scope payload beyond the per-field max_context_chars budget. It does not otherwise explain individual parameters, so it sits just 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?

States a concrete action and artifact: 'Prepare a stateless task-scoped worker package without switching your persona,' and explicitly negates a tempting misreading with 'This tool does not spawn workers.' However, it uses internal jargon ('worker package', 'persona', 'implants') and never names the nearest sibling (get_agent_context) to disambiguate, so an agent must infer the boundary.

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

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

Gives an explicit ordering constraint: 'Require status: prepared before spawning' and 'call validate_subagent_result with YOUR retained contract and the unchanged output. Require valid: true.' That is real when-to-use guidance. It stops short of naming alternatives or stating when this tool is the wrong choice versus get_agent_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 safety (readOnlyHint=true, openWorldHint=false), and the description adds genuine value: it clarifies no network fetch occurs and discloses a concrete retrieval cap (up to 20 cached versions), which signals possible truncation. It doesn't discuss auth or error behavior, so not a full 5.

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

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

Two short, front-loaded sentences with no filler. The scope statement comes first and the boundary constraint second; every clause earns its place.

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

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

An output schema exists, so return-value explanation is not required, yet the description still summarizes returned content (MDC, revision, cached versions). The main residual gap is that rule_id semantics are left entirely undocumented in both schema and description.

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 rule_id has 0% schema description coverage, so the description must compensate. It hints at rule naming via 'user:<name>' but never explains what a rule_id is, its format, or how it relates to the name — partial compensation only.

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

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

States a specific verb (Read) and resource (user:<name> rule) and enumerates what is returned: accepted MDC, revision, and up to 20 cached versions. This distinguishes it clearly from siblings like list_user_rules, refresh_user_rule, and delete_user_rule.

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: 'Read before refresh, enable/disable, rollback or deletion', which names the exact sibling operations that should be preceded by this call. It also states a negative boundary ('Never fetches a URL'), removing an obvious mis-inference given the URL-rule subject matter.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the fallback framing, which is useful behavioral context, but says nothing about auth, rate limits, or result size. With annotations carrying the safety burden, a 3 is appropriate.

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

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

Two sentences with zero waste. The purpose is front-loaded and the routing guidance follows immediately; nothing is padded or redundant.

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

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

An output schema exists, so return values need not be explained, and the description covers purpose and routing well. The only gap is that the include_metadata parameter and its default are left entirely to the schema.

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

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

Schema description coverage is 0% for the single include_metadata boolean, and the description never names that parameter or its default. It does imply which metadata fields the flag toggles (display_name, role, trigger_command), partially compensating, but the mapping to the parameter remains implicit.

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 ('Returns the list of all available agents'), scopes it ('all'), and enumerates the metadata returned. It also names the sibling route_and_load, so an agent can distinguish it without opening any schema.

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

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

Explicitly states the condition for use ('as a fallback when route_and_load is unavailable') and the alternative ('route_and_load'), plus a second use case ('present agent options to the user'). This is the when-to-use/when-else pattern at full strength.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value: it defines the returned flags overridden_by, upstream_changed, and sync_conflicts, and prescribes an action for the last one ('tell the user'). It still does not mention pagination, ordering, or result size limits.

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

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

The opening sentence front-loads purpose, then scope, then ID semantics, then flag semantics, then a prerequisite note — a sensible ordering with no filler sentences. It is slightly telegraphic (fragments such as 'overridden_by marks...') and dense for a two-parameter read tool, but every clause carries 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 a simple read-only listing tool with two optional parameters and an output schema already present, the description covers everything the agent needs: what is listed, how to scope it, how IDs are namespaced, which flags may appear, and when workspace matters. Nothing material is left 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 only 50% and the scope property has neither a description nor an enum in the schema; the description fully compensates by enumerating all four legal scope values, marking 'all' as the default, and explaining the ID namespacing (bare built-in IDs, user:<id>, repo:<id>). It also clarifies the conditional relevance of the workspace parameter beyond the schema's generic text.

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

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

States a specific verb (List) and resource (Markdown workflows) and immediately enumerates the three subtypes it can return (built-in, personal, this repository's). An agent can distinguish this from siblings like get_flow (single fetch), save_flow, or run_flow without opening any schema.

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

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

Gives concrete scope-selection guidance (all/builtin/user/repo, with the default) and the conditional prerequisite 'No workspace is needed except for repo flows', which is exactly the when-to-pass-what guidance an agent needs. It does not, however, name a sibling alternative or state when another tool (e.g. get_flow) should be preferred for a single flow.

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

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

Annotations already declare readOnlyHint and openWorldHint=false, but the description adds real behavioral context: it spans all installation workspaces rather than one, performs no source fetch, and keeps corporate, built-in, and synced personal rules in separate buckets. This goes meaningfully beyond the annotation set.

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

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

Three short lines, front-loaded with what is listed before the scoping caveats. Slightly hurt by the dangling fragment 'Across this installation's workspaces;' which reads as a truncated clause rather than a complete sentence.

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

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

With no parameters and an output schema present, the description need not explain return values, yet it volunteers the key fields and the rule-category separation. Scope and content are covered; ordering, pagination, or size limits are not mentioned but are unlikely to matter for this read-only listing.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The mention of returned fields is a bonus rather than a parameter explanation.

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

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

States a specific verb (List) and resource (this user's URL rule subscriptions), and enumerates what is returned — enabled state, revision, last refresh error. It distinguishes the tool from fetch-style siblings by noting it never fetches the source, though it does not name the alternatives (get_user_rule, refresh_user_rule) outright.

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 scope constraint ('across this installation's workspaces') implies when the tool is appropriate, but there is no explicit when-to-use/when-not statement and no pointer to sibling tools such as get_user_rule for a single rule. Usage is left largely 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 already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: two mutually exclusive input modes and the exact composition of each bundle. It does not disclose what happens if neither mode is supplied or whether loaded implants persist in the session.

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

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

Front-loads the purpose, then structures the two modes and bundle contents as scannable bullets. The bundle listing is not filler — it carries parameter information absent from the schema — so every line earns its place.

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

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

An output schema exists, so return values need no explanation, and the description adequately covers modes and bundle composition for a 3-param, 0-required tool. The remaining gaps are the undocumented default behavior when no mode is passed and the meaning of 'limit'.

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

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

Schema description coverage is only 33% (only task_type is documented in the schema), and the description compensates well: it explains query as a free-form semantic search and supplies the actual enum values for task_type, which the schema lacks (0 enums). The 'limit' parameter remains undocumented in both schema and description, keeping it from a 5.

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 ('Load cognitive implants') and immediately defines what they are ('mental models, reasoning strategies'). The two-mode structure (task_type vs query) and the bundle contents make it fully distinguishable from sibling tools like route_and_load or get_agent_context.

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 'provide ONE of' the two modes, which is strong routing guidance for mode selection, and names concretely what each task_type bundle returns. It stops short of saying when to prefer this tool over siblings (e.g. route_and_load) or which mode fits which situation, so no full 5.

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

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

Annotations declare readOnly=false, idempotent=false, destructive=false, but the description adds real context beyond them: the context is 'immutable', tokens are returned only once, and they must be kept outside prompts and logs. This one-time secret exposure is exactly the kind of behavioral detail an agent needs and cannot get from structured fields.

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

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

Two tight sentences with zero waste. The core capability is front-loaded and the security constraint follows immediately; every clause earns its place.

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

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

With an output schema present, full parameter coverage, and annotations covering the safety profile, the description only needs to carry the non-obvious behavioral bits, which it does (immutability, one-time token return). Minor gap: no explicit note on the create→grant→generate lifecycle position relative to siblings.

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

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

Schema coverage is 100%, so all eight parameters are already richly documented (ttl bounds, max_requests budget, path constraints, owner caps). The description adds no additional parameter meaning, 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 (Capture) and resource (immutable workspace-bound context) and adds the differentiator 'without starting a model', which separates it from local_generate. It does not explicitly name the sibling alternatives, so it's clear but lacks sibling routing.

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

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

The phrase 'without starting a model' implies this is a preparatory step before generation, but there is no explicit when-to-use, when-not, or reference to siblings like local_context_grant or local_context_release. Usage must be inferred from the lifecycle.

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 disclose readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds one genuinely new fact — that grant caps do not reserve shared credits — which matters for credit budgeting, but it omits anything about the returned capability token or how the grant is later revoked.

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

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

One tight sentence with the action front-loaded and no filler. It is arguably under-sized for a five-required-parameter mutation tool, but nothing is wasted and the ordering is correct.

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

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

An output schema exists so return values need not be explained, but for a 6-parameter, 5-required tool in a context lifecycle family the description is too thin — it never explains the returned capability, the relationship to local_context_create, or how the grant relates to local_context_revoke/release.

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 six parameters in detail (owner_token authorization warning, ttl bounds, caps bounded by remaining context budget). The description adds only the credit-reservation nuance around caps, which is a marginal delta over the schema, so the baseline 3 holds.

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

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

The verb+resource is present ('Create a scoped child access capability'), but 'capability' is abstract jargon and the description never says 'context' or 'access grant' — the agent has to map it back to the tool name and title. It also gives no differentiation from siblings like local_context_create or local_context_revoke.

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

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

There is no statement of when to grant versus create/revoke/release, no prerequisites named, and no alternative tool referenced. The second clause is a constraint, not usage guidance, so an agent gets no routing help.

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

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

Annotations already declare destructiveHint and idempotentHint, so the safety profile is covered. The description adds genuine context beyond that: it lists what is destroyed (context/grants) and that work is cancelled, and it explains the mechanism behind idempotency (bounded tombstones) that annotations only flag as true.

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 compact sentence that front-loads the destructive effects before the idempotency note. 'Bounded tombstones' is slightly jargon-heavy, but nothing is wasted.

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

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

An output schema exists, so return values need not be described, and annotations carry the safety profile. The description covers what is destroyed and the intended repeat-release behavior, leaving only the sibling-routing question open.

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

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

Schema description coverage is 100%, with both context_id and owner_token documented as required. The description adds no syntax, format, or relationship detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource (invalidate/release a local context) and names the concrete effects: grants invalidated and work cancelled. It does not, however, differentiate itself from the adjacent sibling local_context_revoke, leaving the agent to guess which one to pick.

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

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

Usage is only implied: 'bounded tombstones permit repeated release' hints that this can be safely re-invoked and is the terminal lifecycle step for a context. There is no explicit when-to-use versus local_context_revoke or when-not-to-use guidance for a tool whose sibling set is crowded with lifecycle operations.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is largely covered. The description still adds real value by disclosing the downstream effects (publication suppression, job fencing) and confirming idempotency with 'repeat safely', but it omits what ownership/permission prerequisites mean in practice and what exactly is destroyed.

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

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

A single dense sentence that front-loads the core verb and resource before the side effects and the idempotency note. Nothing is wasted, though it is terse enough that some context must be inferred.

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, idempotent mutation tool with full schema coverage, complete annotations, and an output schema, the description is largely sufficient: it conveys the action and its consequences. The main residual gap is the absence of guidance on authorization prerequisites beyond what the schema states.

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 grant_id, context_id, and owner_token (including the note that the owner access grant cannot be revoked). The description adds no further parameter-level meaning, so the baseline of 3 applies.

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

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

The description states a specific verb (Revoke) and resource (a local-context grant) and further details the effects: suppressing publication and fencing the active job. It clearly distinguishes the action from sibling write operations like local_context_grant or local_context_create, though it never names an alternative explicitly.

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

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

Usage is implied by the revoke semantics, and 'repeat safely' signals that repeated calls are tolerated, but there is no explicit when-to-use guidance or distinction from the nearby local_context_release sibling. No exclusions or prerequisites are 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?

Annotations already establish the safety profile (readOnly=false, destructive=false, openWorld=false). The description adds genuine value beyond them by declaring the asynchronous contract ('promptly return its job ID') and the no-side-effect boundary ('never executes output or spawns agents'). It omits idempotency-by-request_id behavior and cancellation, but the annotations mean the bar is lower.

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

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

Two short, front-loaded sentences with zero filler. The core action is stated first, followed by the follow-up step and the scope boundary.

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

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

With an output schema present, return values need no explanation, and the description correctly focuses on the async pattern and the no-execution boundary. Minor gaps remain: it doesn't mention the cancel tool or that job deadlines are capped by grant expiry, though the schema covers timeouts.

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% across all 9 parameters, so the schema fully documents seed, task, cache_mode, request_id, timeout, and token limits. The description adds no parameter-level detail beyond that, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource - 'Submit one bounded textual completion' - and clarifies the return contract ('promptly return its job ID'). This clearly distinguishes it from local_generation_result, which is the polling counterpart.

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

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

Explicitly routes the agent to the next step ('Poll local_generation_result'), giving clear usage context. It does not, however, state conditions for when-not to use this tool or mention local_generation_cancel as an alternative path.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the cancellation propagates to all pollers, and cleanup fences/reaps run before the job reaches terminal state, which affects sequencing expectations.

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

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

A single dense sentence with the action front-loaded and no filler. The 'fences/reaps' jargon is terse to the point of being slightly opaque, but nothing is wasted.

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

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

Return values need not be described since an output schema exists, and annotations cover idempotency and destructiveness. The description supplies the multi-poller scope and pre-termination cleanup sequence, leaving only alternative-tool routing unaddressed.

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

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

Schema description coverage is 100% with three documented parameters (job_id, context_id, capability_token), so the schema carries parameter meaning. The description adds no format, ownership, or validation detail beyond it; 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: cancel a local generation job. The phrase 'for all pollers' scopes the effect and separates it from merely reading a result via local_generation_result or local_inference_status, though no sibling is named explicitly.

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

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

'Explicitly cancel' implies the use case (deliberate termination, as opposed to implicit teardown such as local_context_release), but the description never states when NOT to use it or which alternative tool to prefer. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, openWorldHint=false, and idempotentHint=true, so the safety profile is covered. The description adds a genuinely non-obvious behavioral trait: that dropping a poll does not cancel generation, and that job state/output is 'retained'. It could say more about what happens after a job expires or completes.

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

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

A single front-loaded sentence that states the action first and then the key behavioral caveat, with no filler. It is efficient but arguably too terse to be maximally useful.

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

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

An output schema exists, so return values need not be explained, and annotations cover the read-only/idempotent profile. The description adds the one surprising behavior an agent needs (poll disconnect is harmless), though the routing relationship to local_generate's job_id could be clearer.

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 job_id, context_id, wait_seconds, and capability_token are already documented in the schema (including the wait_seconds bounds and its non-dispatch semantics). The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('Read retained job state/output'), which is clearly distinguishable from siblings like local_generation_cancel and local_inference_status. It does not explicitly name or contrast with those siblings, so it stops short of a 5.

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

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

Mentioning that 'disconnecting a poll never cancels generation' implies this is the polling/read path after local_generate, but the description never states when to use it versus local_inference_status, local_generate, or local_generation_cancel. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and idempotentHint=true, so the safety baseline is covered. The description adds genuinely new behavioral context beyond that: no model is started, no network call is issued, and no host paths or secrets are exposed — the kind of disclosure an agent needs before calling a status probe in a sensitive environment.

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

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

Two tight sentences with zero filler. The content enumeration comes first and the safety/no-side-effect guarantees second, which is the correct front-loading for an agent deciding whether to call it.

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 parameters, a full output schema covering the returned fields, and annotations covering the safety profile, the description needs only to add what structured data cannot express — and it does exactly that by stating the absence of model starts, network calls, and secret/path exposure.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description appropriately adds no parameter guidance because there is nothing to parameterize, and it instead spends its words on scope and safety.

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

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

The description gives a specific verb (read) plus a resource (local inference status) and enumerates exactly what the status covers: enabled state, readiness, capabilities, job counts and owner hard limits. It is clear what the tool does, but it never differentiates itself from related siblings such as local_generation_result or get_agent_context, so it falls short of a 5.

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

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

Usage is only implied: an agent can infer this is the read-only status probe for local inference. The clause 'Performs no model start or network call' functions as a soft when-not (this is not the generation tool) but never names local_generate or any alternative, and there are no explicit prerequisites or exclusion conditions.

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?

Far beyond the annotations: it discloses two independent sinks (history.md via HistoryWriter, Langfuse), that Langfuse is a no-op without LANGFUSE_PUBLIC_KEY/SECRET_KEY, that writes are backgrounded and can be dropped by a full queue, dedup and default field values, the unverified/mismatch attribution path with 'Do not retry such a call', the fallback journal, and the exact conditions for the only remaining request-level rejection. Annotations only cover safety hints, so the description carries and fully discharges the behavioral 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 imperative call sequence is front-loaded, which is correct, but the body is a very dense ~400-word wall that re-states the persona key list already enumerated in the schema and explains the return payload that the output schema already defines. Much is load-bearing, but there is real redundancy that an agent must wade through.

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 13-parameter tool with nested objects, async sinks, fallback routing and a rejection path, the description covers the full picture: happy path, subagent exclusion, attribution failure handling, warming-up skips, and error surfacing. Nothing needed 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%, so the baseline is 3, but the description adds real constraints beyond the schema: query must be verbatim with no paraphrase or conversation summary, workspace is the working directory, persona must be copied verbatim with all 7 keys, persona_action is only valid together with persona, and files/tags are JSON arrays. It repeats some schema content (the 7 keys), keeping it short of a 5.

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

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

The first sentence names a specific verb+resource ('End-of-turn logger') and immediately situates it in the turn lifecycle ('Compose the answer... call this tool... then deliver the final answer'). This is unambiguous and clearly distinct from siblings like read_history or get_agent_context.

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 (end of turn, with the composed final answer) and when not to ('Compact subagents return their data envelope without calling this tool'). It even gives the sequencing relative to delivering the answer, which is the key orchestration detail an agent needs.

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 and openWorldHint, so the description carries real behavioral burden and delivers: it discloses index build/rebuild triggers, the 50,000-character budget with per-field truncation caps, the 'truncated'/'omitted' escape hatches, machine-sync merge semantics (one per entry hash), and the no-project fallback journal. That is far beyond what the annotations 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 mode-by-mode bullets are well front-loaded and mostly earn their place, but the entire closing section restates the return payload ({entries, total, mode, omitted?, instruction?, workspace, pid, history_last_error?} plus per-mode entry fields) even though an output schema exists, making it redundant bulk.

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 read tool with subtle truncation, index, and sync behavior, the description covers every mode, the fallback path without a project, and the sync/merge rules. Since an output schema exists, the only redundancy is the return-value restatement, not a gap.

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

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

Schema coverage is already 86%, so the baseline is 3, but the description adds real semantics: limit applies to newest entries, since is an ISO8601 prefix and inclusive, offset skips newest-or-nearest, and entry_id suppresses all other arguments. It also explains the machine label versus 'local' distinction beyond the schema's phrasing.

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

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

The first sentence names a specific verb and resource ('Read recent history entries') and immediately enumerates the three distinct modes (list, semantic search, single-entry read). No sibling tool covers history reads, so the tool is unambiguously distinguishable. An agent knows exactly what this does from the opening line.

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 bulleted structure gives explicit conditional guidance for each argument: no query means recency listing, query means semantic nearest, entry_id means whole entry with other args ignored. This is strong when-to-use coverage, though it never names an alternative tool or states a when-not-to-use condition, which keeps it below a 5.

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

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

Goes beyond the annotations by describing the response contract (NO_CHANGE for identical content, full SUCCESS bundle when content changes) and that replacement is atomic. There is mild tension with idempotentHint=false, since identical input yielding NO_CHANGE reads as idempotent behavior, but the atomic swap of a live activation plausibly explains the non-idempotent hint rather than contradicting 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?

Three short sentences, front-loaded with the protocol identifier and the core action, followed by the gating condition and the return contract. Nothing is repeated and every sentence carries distinct 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 a mutating, nested-object tool with an output schema present, the description supplies the gating condition and the two possible outcomes, which is what an agent needs to call it safely. It omits prerequisites (e.g. that a prior SUCCESS/NO_CHANGE activation must exist) but the schema's verbatim-copy requirement covers most of that.

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%, including detailed per-field notes on the nested persona object, so the schema carries the parameter burden. The description adds no format, validation or sourcing detail for query, chat_history or current_persona beyond what the schema already states, 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 (refresh the current role's complete bundle) and adds a delimiting clause ('without choosing an agent') that separates it from agent-selecting siblings like route_and_load or set_flow_persona. The sibling is not named outright, so the differentiation requires a small inference.

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

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

Gives an explicit when-to-use and when-not-to-use pair: 'Call only when additional skills/implants are needed, never on ordinary continuations.' It does not name an alternative tool to use on ordinary continuations, so the routing guidance is strong but not fully closed.

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