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

With no annotations, the description carries the full burden and does so thoroughly: it discloses the database mutation (a single row insert into contracts at ~/.ferrycat/mesh.db), the SHA-256 snapshot computation, a stale-buffer warning heuristic (files modified within 3 seconds), and the full lazy-expiry lifecycle with tiered TTLs. This is exactly the behavioral context an agent needs before a mutating call.

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 markdown sectioning (Purpose / Usage Guidelines / Behavior & Side Effects / Return Value) makes the length appropriate for a 10-parameter mutating tool, and the purpose is front-loaded. There is some redundancy — sensitive-file blocking is stated in both the description body and repeated again in the schema — which keeps it from a 5.

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

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

Although there is no output schema, the description explicitly enumerates the return shape ({contract_id, status, created_at, files[...], warning?}) and even flags fields that are omitted from the response. Combined with the lifecycle and failure-mode detail, nothing an agent needs to invoke this 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 schema already documents all 10 parameters and the baseline would be 3. The description adds value beyond it by explaining the tiered TTL defaults tied to task_type, and by noting that requester_agent/target_agent/TTLs are NOT echoed in the return value. It does not add much per-parameter syntax detail, so a 4 rather than 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 description opens with a specific verb, resource, and mechanism ('Dispatch a task or code review contract to another local AI agent host via the shared SQLite WAL mesh') and immediately refines it ('Registers a new contract in SUBMITTED status with full-file SHA-256 fingerprint snapshots'). This is clearly distinct from siblings like poll_next_task and inspect_mesh_state, which are named as alternatives.

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

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

It provides explicit 'When to use', 'When NOT to use' with named sibling alternatives (poll_next_task for claiming/executing, inspect_mesh_state for status), and prerequisites (shared filesystem access, pointer files saved on disk, sensitive-file blocking). Nothing is left to inference.

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

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

With no annotations, the description carries the full burden and delivers: it discloses the database mutation (claimed_at=nowMs reset, extend_count increment), hard quotas (max 5 renewals per holder), an absolute lifetime ceiling (created_at + 4 * queue_ttl_sec), and the rejection condition. It also warns that expiry transitions the contract to TIMED_OUT.

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?

Content is front-loaded with the core action and organized under clear headings, and virtually every line carries operational information. The markdown-section framing is heavier than necessary for a tool description and the return-value block is dense, but nothing is truly 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?

For a mutation tool with no annotations and no output schema, the description supplies the missing pieces: side effects, quota limits, failure conditions, prerequisites, and an explicit return shape. An agent has everything needed to call it correctly and to anticipate rejections.

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 contract_id, agent_id, and claim_token in detail; baseline is 3. The description adds the holder-must-match precondition but never explains claim_token's lease role, and it references 'proposedExpiresAt' which is not an input in the schema, a minor source of confusion.

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 ('Heartbeat renewal ... restarts the active execution window of a CLAIMED contract') and immediately frames it as timeout prevention. It is clearly distinguishable from siblings that deliver, release, or fail a contract, which are named later.

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 ('periodically during long-running tasks before the active exec_ttl_sec countdown expires') and three when-NOT-to-use cases, each routing to a concrete sibling (fulfill_contract, release_contract, fail_contract). Prerequisites are stated: caller must be current holder and contract must be CLAIMED.

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

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

With no annotations, the description carries the full burden and does so: it discloses the exact mutation (status='FAILED', error_reason prefixed 'WORKER_FAILED:', completed_at=nowMs) and an edge case that would otherwise surprise an agent — a late call after TTL expiry yields TIMED_OUT while preserving the reason. Return shape is also spelled out despite no output schema.

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

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

Front-loaded single-sentence summary, then short labeled sections — well structured and scannable. It is slightly longer than strictly necessary (Return Value repeats the shape the agent could otherwise infer, and the side-effect detail is dense), but no section is 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 terminal-mutation tool with no annotations and no output schema, the description covers authorization prerequisites, exact side effects, the expired-window edge case, and the return value. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning by tying the caller-identity requirement ('caller must be the current holder') to agent_id/claim_token and stressing the reason is mandatory and surfaced to the requester. It does not add format or length guidance beyond the schema's min/max constraints.

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

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

States a specific verb (mark terminal FAILED) and resource (a CLAIMED contract), plus the distinguishing constraint 'claimed'. The usage guidelines explicitly name fulfill_contract and release_contract as the alternatives for success and recoverable cases, so an agent can route without opening other schemas.

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 when-to-use (unrecoverable failure such as fatal syntax error, broken test suite, missing environment) and two explicit when-NOT-to-use cases with the sibling to use instead. Prerequisites (current holder, non-empty reason) are also stated.

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

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

No annotations exist, and the description carries the full burden well: it discloses the authorization requirement (agent_id must match target_agent), the exact TOCTOU soft-failure policy with strike counts and terminal outcomes, the Ajv validation retry ladder (2 recoverable, 3rd terminal VALIDATION_FAILED), and what data is preserved on failure. These are non-obvious side effects an agent could not infer from the schema.

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

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

Well front-loaded with a one-sentence summary, then headed sections that map to purpose, usage, behavior and returns. It is long but nearly all of it is load-bearing; the return-value enumeration and repeated strike-buffer detail are slightly redundant but justified given there is no output 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 6-param mutating tool with no annotations and no output schema, the description covers prerequisites (claim_token, CLAIMED status), failure modes and terminal statuses, and spells out the return shape itself. 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%, so the schema already documents every parameter, including claim_token and the fixes pattern. The description reinforces the roles of result_summary, structured_output and artifacts_pointers but adds little syntax or format detail beyond what the schema states; baseline 3 applies.

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

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

Names a specific verb and resource (submit deliverables for a CLAIMED contract) and explicitly describes the scope: delivery, baseline verification, schema validation, transition to COMPLETED. It distinguishes itself from release_contract and fail_contract by name, so an agent can route between them without opening a schema.

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

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

Provides an explicit 'When to use' and a 'When NOT to use' section that names the correct alternatives (release_contract to re-queue, fail_contract to record failure) along with a concrete accidental-modification recovery path (git stash, verify_contract, fixes in structured_output).

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

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

With no annotations provided, the description carries the full behavioral burden and does so well: it states zero side effects, a pure read-only SELECT against SQLite WAL, no row mutation, no sweeps, and no database locks. It also explains the dynamic is_logically_expired calculation based on queue or execution TTL, which is non-obvious behavior an agent would otherwise miss.

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

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

The description is front-loaded with the core read-only purpose and then organized into clear sections for usage, behavior, and return value. The return-value structure is detailed but earns its place because there is no output 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?

Given the lack of annotations and output schema, the description is complete enough for correct invocation: it covers purpose, alternatives, side effects, lock behavior, expiration logic, and the returned object shape. No critical context for a 4-parameter optional-filter observability tool appears to be 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 all four parameters are already documented in the schema; the baseline is therefore 3. The description adds some meaning by explaining the target_agent filter for monitoring a specific agent’s queue, but it does not add much beyond the schema for limit, status, or contract_id.

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

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

The description states a specific verb and resource: a strictly read-only query of contracts, execution progress, outputs, diagnostic counters, and failure causes in the multi-agent mesh state. It clearly distinguishes the tool from sibling operations by naming poll_next_task, dispatch_contract, and verify_contract as alternatives for other purposes.

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 explicit when-to-use cases such as checking whether a dispatched contract was claimed or completed, inspecting result summaries, and monitoring queue depth via target_agent. It also gives explicit when-not-to-use cases with named alternatives for claiming, dispatching, and verifying file pointer hygiene.

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

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly: it discloses the atomic DB mutation, optimistic concurrency check, TTL window start, lazy TTL sweep, fingerprint verification order, POINTER_STALE handling, and queue advancement. It also describes both success and empty-queue return shapes.

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

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

The description is front-loaded and sectioned into purpose, usage, behavior, and return value, making it scannable despite its length. It is appropriately detailed for a stateful claiming operation, though some repetition of the atomic-claim concept across sections keeps it short of perfect conciseness.

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 with no annotations and no output schema, the description is complete enough to call correctly: it explains side effects, concurrency behavior, TTL behavior, stale-pointer handling, and return values. An agent has the operational context needed without opening additional documentation.

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 schema already documents agent_id including its default from the AGENT_NAME environment variable. The description reinforces that the task is assigned to this agent, but adds little parameter-level meaning beyond the schema, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource: atomically claim the oldest pending SUBMITTED contract assigned to this agent, including fingerprint verification. It clearly distinguishes the tool from siblings by naming inspect_mesh_state for non-claiming inspection and dispatch_contract for creating contracts.

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 explicit when-to-use guidance (periodically or when notified to discover and claim pending tasks) and explicit when-not-to-use guidance with named alternatives for inspection and contract creation. It also adds a relevant ADR constraint about pointer immutability.

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

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

No annotations exist, so the description carries the full burden and it does: it discloses exact DB mutations (claimed_at=NULL, queued_at=nowMs, extend_count=0, release_count incremented), what is deliberately preserved (retry_count circuit-breaker quota, with the anti-laundering rationale), the audit-trail format appended to error_reason, and hard limits (max 3 releases, absolute lifetime ceiling of 4 * queue_ttl_sec). This is exactly the side-effect detail a mutation tool 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-loaded with the verb/effect in the first sentence, then cleanly partitioned into Purpose, Usage, Behavior, and Return Value. Slightly longer than necessary — the one-line Purpose section largely repeats the headline — but every other sentence carries distinct operational 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?

Although there is no output schema, the description spells out the full return shape ({ ok, contract_id, status, release_count, max_releases, message }). Combined with the side-effect and limit disclosures, an agent has everything needed to invoke this safely and interpret the result.

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

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

Schema description coverage is 100%, so each of the four parameters, including claim_token's provenance from poll_next_task, is already documented in the schema. The description restates the agent_id/target_agent match and CLAIMED-status prerequisite but adds no new syntax or format detail beyond that. Baseline 3 is appropriate 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?

States a specific verb (release), resource (contract), and target state (back to queue tail as SUBMITTED with a fresh queue window). The usage-guidelines section explicitly contrasts it with fail_contract and extend_ttl, so an agent can distinguish it from every sibling without opening a schema.

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

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

Provides explicit 'when to use' (claimed by mistake, missing local deps, need to switch branches) and an explicit 'when NOT to use' pair that names the correct alternative for each case (fail_contract for permanent failure, extend_ttl for needing more time). Prerequisites are stated outright (caller must be the current holder, status must be CLAIMED).

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

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

With no annotations at all, the description carries the full burden and does so: zero side effects, never mutates DB, never alters contract status, never consumes a TOCTOU strike. It also discloses that all pointer files are checked and enumerates the drift reasons (SIZE_MISMATCH, CONTENT_CHANGED, FILE_MISSING).

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 one-line summary and well-structured under headers, with the critical branch-on-fulfillable warning placed last for emphasis. It is somewhat long, and the Behavior section partly re-states the read-only claim made in the opening line, but nearly every sentence carries actionable information.

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

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

No output schema exists, and the description fully documents the return shape and the crucial valid vs. fulfillable distinction, including the terminal-state edge case. Combined with side-effect disclosure and the ADR-0004 rule, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so contract_id, agent_id, and claim_token are already documented in the schema; the description adds no syntax or format detail for them. Baseline 3 applies since the schema does the heavy lifting on parameters.

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 ('pre-flight consistency check ... audits on-disk pointer files against the baseline SHA-256 snapshot') and immediately scopes it as read-only. The Usage Guidelines name the exact siblings it is not (fulfill_contract, extend_ttl), so an agent can route 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?

Explicit 'When to use' (before fulfill_contract while holding a CLAIMED contract; when debugging a blocked fulfill) and 'When NOT to use' with named alternatives. It even supplies the remediation path (restore/stash, put changes in structured_output.fixes) when verification reports dirty files.

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