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

With no annotations, the description carries the full load. It reveals a mutation (a reciprocal request is sent) but does not say what happens on success (is the connection established for both sides?), whether the call is idempotent, what error occurs if no pending request exists, or whether it is reversible.

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 action in one sentence, followed by short Args/Returns blocks. No wasted prose; the only weakness is that the terse Args lines sacrifice detail for brevity.

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 the 'Returns: Confirmation' line is sufficient and no return explanation is owed. Still missing for a state-changing, unannotated tool are the precondition (pending request), postconditions, and the effect of the intro argument on the peer.

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 0%, so the description must compensate, and it does partially: peer_pubkey is identified as the requester's key and intro as a short response. However, 'Short response' is vague about purpose and constraints (length, visibility to the peer), and the required/optional split (intro has a default) is not mentioned.

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 ('Accept a connection request') and adds the key mechanic of sending a reciprocal request, which separates it from a plain read of requests. It does not explicitly contrast with a4a_request_connection or a4a_get_connection_requests, but the mutual/reciprocal framing makes the directionality clear.

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

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

No guidance on when to call this versus a4a_request_connection (outgoing) or a4a_get_connection_requests (which surfaces incoming requests). The prerequisite — that a pending incoming request from peer_pubkey must exist — is implied by 'requester' but never stated.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it explains Bitcoin notary timestamps, signature and delegation checks, revocation listing, evidence limits, header-source requirements, the default blockstream.info source, and the UNVERIFIABLE outcome when headers are unavailable. It also states that a missing revocation does not prove global absence and that retrying without headers is pointless.

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

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

Although lengthy, the description is front-loaded with purpose and scope, then verification mechanics, then args and returns. Every sentence contributes operational meaning, and none is redundant 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?

The tool is complex and involves historical authority verification, external block headers, and nuanced failure states. The description covers the verification source, the meaning of the three states, evidence limits, and next actions; with an output schema present, it is complete enough for correct invocation and interpretation.

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

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

Schema description coverage is 0%, but the description fully compensates for the single parameter by specifying event_id as an Event ID with 64 lowercase hexadecimal characters. That is the format detail an agent needs beyond the schema's bare string type.

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: checking facts about a historical event and reporting the limits of authority evidence. It also distinguishes this from fresh deals, where party signatures decide, and scopes it to old reviews, agreements, or attestations, so an agent can tell it apart from ordinary agreement inspection.

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 and when-not-to-use guidance: use it for someone else's history such as an old review or attestation, not for fresh deals. It does not name a specific alternative MCP sibling to use instead, which keeps it from the top score.

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, so the description carries the burden, and it does so well: it discloses the mutual-signature semantics, that one signature makes nobody a party, and that the operation concludes the agreement. It does not mention auth requirements or failure modes, keeping it just 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?

Front-loaded with the core action, then rationale, then args/returns. Mostly tight, though 'thereby conclude it' and 'conclude a deal' slightly repeat the same idea. Every other sentence earns its place.

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

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

An output schema exists, so return-value detail is not required, yet the description still notes the return is the concluded agreement's ID that subsequent operations reference. Combined with the clear workflow and param source, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 0% and only one param exists, so the description must compensate. It does: it tells the agent exactly where the agreement_id comes from (a4a_get_agreements) and its required state ('WAITING FOR YOUR SIGNATURE'), adding meaning well beyond the bare string type in the schema.

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

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

The description uses a specific verb+resource combination ('Sign an agreement') and states the outcome ('thereby conclude it'). It distinguishes the action from a4a_make_agreement and a4a_get_agreements by clarifying this is the second-party cosign step that finalizes a proposed deal.

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

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

Explicitly states when to use this: when a proposal marked 'WAITING FOR YOUR SIGNATURE' appears in a4a_get_agreements. It names the sibling tool and the precondition, and warns that without this step two independent agents cannot conclude a deal.

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 does: one initial attempt plus three retries, terminal states acknowledged/dead_letter, what 'acknowledged' means (recipient signed a receipt), how ack_status differentiates received/processed/failed, automatic relay resolution, and automatic encryption/wrapping. It also discloses a side effect beyond the return value — every delivery is written to the local delivery journal — and points to a4a_delivery_status for post-hoc ACK recovery.

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-sentence purpose and sibling exclusion, then behavior, then Args, then Returns. No sentence is padding — retry counts, envelope semantics, journal fallback, and the deprecation date each change how an agent calls or interprets the tool.

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

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

For a four-parameter mutating tool with zero annotation coverage and zero schema descriptions, this is about as complete as it gets: retry behavior, failure handling, journaling side effect, encryption guarantees, relay resolution, and even a summary of return values despite an output schema existing. Nothing an agent needs to invoke it correctly appears 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 0%, so the description must compensate, and it documents all four parameters: to_pubkey as an owner-authorized recipient key, text as plaintext with automatic encryption and metadata wrapping, conversation_id as an optional 64-character lowercase hex handle signed inside the gift wrap, and new_letter as the new-vs-answer flag. This is materially more than the schema's bare string/boolean types and defaults.

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 ('Deliver a private message and wait for the recipient's signed ACK') and immediately separates itself from the sibling a4a_reply by name, so an agent can route without opening either schema. The blocking/waiting semantics are part of the stated purpose, not buried 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?

Explicitly says 'To answer a received letter use a4a_reply(seq) instead... This tool is for new letters,' naming the alternative and the condition that selects it. It also flags a forward-looking requirement (new_letter required from 2026-10-11), which prevents a foreseeable misuse.

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

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

With no annotations, the description carries the full burden and does well: it discloses the hidden side effect that this rechecks relays and *records* a LATE acknowledgement, and enumerates the four possible outcomes including the ambiguous 'sending'/'interrupted' states. It stops short of stating auth requirements, idempotency of repeated polls, or rate limits.

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

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

Front-loaded with the core action, then a one-sentence rationale, then a compact outcome glossary that directly aids interpretation. No filler sentences.

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

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

An output schema exists, so return structure needn't be explained, yet the description still supplies the outcome semantics that a bare schema would not convey. The missing piece is whether polling is safe/idempotent and whether recording a late ACK has side effects on other state.

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 0%, so the description must compensate, and it does: delivery_id is documented as 'the 32-character delivery_id returned by a4a_deliver,' giving both the expected format and provenance. Only the single parameter exists, so the gap is minor.

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

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

States a specific verb and resource: 'Report a journaled a4a_deliver outcome and look again for a late ACK.' It ties the tool to its sibling a4a_deliver and makes clear this is a status/recheck operation rather than a send, so an agent can distinguish it immediately.

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 describes the triggering condition: a recipient's receiver was offline and acks later, 'often long after a4a_deliver returned dead_letter,' which is exactly when to re-invoke this. It lacks a stated when-not/alternative, though no sibling performs this recheck.

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 well: it confirms nothing is sent, explains the relay-owner rationale, discloses that it refuses letters that already left, and states that history is preserved and the operation id is not freed. That is unusually rich behavioral context for a mutation 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?

Front-loads purpose and the no-send guarantee, then follows with the when-to-use condition and the exclusion. It is a bit long across three paragraphs and includes rationale ('the content is encrypted, who talks to whom is not'), but nearly every sentence contributes actionable guidance.

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 covers safety, preconditions, exclusions, and side effects thoroughly. The only real gap is the missing explanation of the lease_token parameter, which an agent cannot infer from the schema 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?

Schema coverage is 0% and there are two required parameters. The description gives some meaning to operation_id (it is not freed, replacement must use a new id) but says nothing about lease_token, so half the inputs remain unexplained in both schema and description.

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 ('Give up on a PREPARED letter') and immediately clarifies the effect ('Never sends anything'). It distinguishes itself from the sibling a4a_dialogue_reconcile by name, so an agent can route correctly without opening 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?

Explicitly states when to use it ('only when a prepared letter is refused because the configured relay set changed') and when not to ('dispatching, unknown and accepted outcomes need a4a_dialogue_reconcile, not disposal'). Names the alternative tool and the condition that selects it.

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

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

With no annotations, the description carries the full burden and does well: it discloses encryption at rest, an 8192 UTF-8 byte limit, that checkpoints are untrusted context rather than authority, and that file-shaped checkpoints are redacted on history reads. It does not explain lease-token ownership, overwrite behavior, or retention, so it is strong but not complete.

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

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

The description is three compact sentences with the core action and limit front-loaded. Every sentence adds distinct information about size, trust semantics, or redaction.

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 two-parameter mutation tool with no annotations and no output schema, the description is adequate on purpose, size, encryption, and trust handling. However, it omits the meaning of the required lease_token and does not say what is returned or whether prior checkpoints are replaced.

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 must compensate for both required parameters. It adds the byte-size constraint for 'text', but says nothing about 'lease_token', leaving a required operational parameter completely unexplained.

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?

It states a specific verb and resource ('Persist an encrypted checkpoint') and includes a concrete size limit. The purpose is clear, though it does not explicitly distinguish itself from dialogue siblings such as a4a_dialogue_history or a4a_dialogue_send.

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 explains the security semantics of a checkpoint but gives no guidance on when to create one versus using a4a_dialogue_send, a4a_dialogue_history, or other dialogue tools. No alternatives or exclusions are named.

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

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

With no annotations, the description carries the full burden and it does disclose the most surprising trait: this produces no network ACK and no proof of an external action, so the agent won't assume delivery was confirmed remotely. It omits other mutation-relevant behavior — whether the lease is released, what happens on failure, idempotency, and permission requirements.

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

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

Two short sentences, front-loaded with the core action and followed by the caveat. The 'no network ACK or proof' line slightly restates 'locally only' but earns its place as a warning against misinterpreting the result.

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 four-parameter mutation tool with no annotations, no output schema, and 0% schema description coverage, the definition is too thin. The undefined status vocabulary and lease_token semantics are the real gaps an agent needs filled to invoke this correctly.

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

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

Schema description coverage is 0%, so the description must explain all four parameters. It only clarifies 'reconciled' (required for unknown work); seq, lease_token, and critically 'status' are left entirely unexplained — status is a bare string with no enum, so the agent must guess valid values like processed/failed.

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: marking this conversation's incoming seq as processed or failed, scoped to 'locally only'. That 'locally only, no network ACK' qualifier meaningfully separates it from siblings that perform real delivery or reconciliation, though it never names a sibling explicitly.

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

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

It gives one conditional rule — unknown work requires reconciled=True after explicit reconciliation — which implies this runs after a4a_dialogue_reconcile for unverifiable cases. But it never says when to call this versus a4a_dialogue_abandon or a4a_inbox_complete, nor what precondition (holding a lease) must be met.

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

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

With no annotations, the description carries the full burden, and it does disclose real behavior: results are bounded, paging is backwards, file references are hidden, and history loading never fetches blobs. However, 'checkpoint' is left ambiguous — it is unclear whether calling this advances/mutates a checkpoint or merely reads up to one, and nothing states whether history entries are consumed or marked as read.

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 core action, then paging rule, then the attachment caveat. No filler or repetition.

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?

Paging and attachment handling are covered, but with no annotations, no output schema, and 0% parameter documentation, the description should also state what a page contains and whether the checkpoint is mutated. The 'before' vs 'next_before' mismatch leaves a concrete gap for a 2-parameter tool.

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

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

Schema coverage is 0% and neither parameter is described. Worse, the description names 'next_before' while the schema parameter is 'before', which can mislead an agent into passing a nonexistent argument. Only the 'zero selects the latest page' clause maps usefully to 'before'; lease_token gets no meaning beyond the required flag.

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 (read bounded history and checkpoint) on a specific resource, scoped to 'the current lease', which separates it from sibling dialogue tools like a4a_dialogue_send or a4a_dialogue_checkpoint. The phrase 'untrusted history and checkpoint' is jargon-heavy but recognizable to an agent already in the a4a dialogue flow.

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?

Implies a precondition (an active lease) and routes blob retrieval to a separate a4a_open_file call, which is useful routing. It never says when to use this over a4a_read_private or a4a_inbox_next, nor how a lease is obtained (a4a_dialogue_lease exists), leaving the selection decision implicit.

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

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

With no annotations the description carries the full burden. It does disclose two meaningful behaviors: the renewal duration and the side effect of releasing unfinished work (left unknown, not auto-retried). It omits what happens on lease expiry, invalid tokens, or failure modes, which for a lease/mutation tool is a notable gap.

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

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

Two tight sentences; the primary action and duration are front-loaded, and the consequence warning follows. No filler, though a slightly fuller structure with the token source would have been more 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?

No output schema and no annotations, so the description should do more: it never says where the lease_token comes from, what a successful renew returns, or whether the lease token changes. It is adequate for the action semantics but incomplete for correct invocation.

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

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

Schema coverage is 0% and both parameters carry only titles. The description supplies the enum values for action (renew/release), which is real added value absent from the schema, but lease_token (how to obtain it, format, required) gets no 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 pair (renew/release) on a concrete resource (the dialogue lease) with the duration (300 seconds). An agent can tell it is about lease lifecycle rather than dialogue content, though it does not name any sibling as an alternative.

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 implicit: renew to hold the lease, release to give it up, with a warning that releasing unfinished incoming work leaves items unknown rather than retried. There is no explicit when-to-use statement or comparison against siblings like a4a_dialogue_abandon or a4a_dialogue_complete.

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 behavioral burden well: it discloses lease semantics, metadata-only behavior, token saving, untrusted-data handling, hidden file references, and separate attachment retrieval via a4a_open_file. It is rich on safety and side effects, though it leaves some lifecycle and return-shape details implicit.

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 primary purpose and then adds security and usage details in a compact sequence. Most sentences earn their place, but some phrasing is dense and slightly cryptic, such as the hidden file-reference 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?

For a complex dialogue-opening tool with no annotations and no output schema, the description covers the important behavioral context: leasing, history bounds, token preservation, trust boundaries, file-handle handling, and owner enablement. It is close to complete, though it does not clarify the exact bounded history or token lifecycle.

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

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

The schema has 0% description coverage for peer_pubkey, so the description must compensate. It does so by explaining the empty-peer versus explicit-peer behavior and outbound conversation semantics, though it does not specify the expected pubkey format.

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

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

The description clearly states the core action: lease one permitted conversation for this MCP process and read bounded history. It distinguishes the two main modes via empty versus explicit peer, though it does not explicitly name sibling tools such as a4a_dialogue_lease or a4a_dialogue_history.

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 usage conditions: an empty peer selects unfinished work without an active lease, while an explicit peer starts an outbound conversation, and no unleased work returns metadata only. It also states the owner dialogue-enable prerequisite, but does not directly route the agent to alternative siblings for related 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?

With no annotations the description carries the full burden, but it does add real behavioral context: it is a non-mutating read-back, it never republishes, and its result may legitimately be inconclusive ('Missing evidence stays unknown'). It still omits what the call returns, whether it needs authorization, and what happens when the lease_token is stale or invalid.

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

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

Two short sentences with no padding, and the core directive ('read back ... never republish') is front-loaded. The second sentence is somewhat aphoristic rather than procedural, but it is compact and adds epistemic guidance.

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 two-parameter tool with no annotations and no output schema, the agent needs to know parameter meaning and what a successful or unknown result looks like. The description supplies neither, and the lease vs. operation relationship is entirely unaddressed.

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

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

Schema coverage is 0% and both parameters (lease_token, operation_id) are undocumented. The description alludes to an 'outgoing operation', loosely mapping to operation_id, but says nothing about lease_token — neither its role nor its relationship to the dialogue lease tools. It does not compensate for the coverage gap.

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 back') and object ('an uncertain outgoing operation'), so the general intent is graspable. But it never names a sibling tool as the alternative (e.g., a4a_dialogue_history, a4a_dialogue_checkpoint) and abstracts the reconciliation purpose into metaphor, so distinguishing it from other dialogue tools requires 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?

'never republish it' implicitly tells the agent what this tool is not for, and 'uncertain outgoing operation' hints at the use case. But there is no explicit when-to-use statement, no mention of the sibling reconciliation/checkpoint tools, and no prerequisites such as when an operation becomes 'uncertain'.

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 well: it discloses the 32768-byte cap, the mandate prerequisite, idempotency semantics via operation_id, and the important caveat that relay acceptance does not confirm peer receipt or processing. It omits error/failure behavior and what a lease token is, keeping it from a 5.

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

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

Two short paragraphs, front-loaded with the action and its hard limits, followed by the non-obvious semantics. Every clause adds information an agent needs; nothing is 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 covers preconditions and idempotency but leaves gaps: it never explains how to acquire the lease token, and only hints at return values via 'return their state'. Adequate, but an agent could still call it wrongly on the lease path.

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 must compensate for three bare parameters. It explains operation_id semantics (stable, same-text reuse) and the text size limit, but lease_token is only alluded to as 'a lease' with no explanation of how to obtain or scope it.

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

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

States a concrete verb and resource ('Send ... UTF-8 bytes') plus the mechanism used ('using a lease and a stable operation_id'), which is distinctive from siblings like a4a_send_private or a4a_reply. It stops short of naming an alternative tool for the non-dialogue send paths, so it is clear but not fully sibling-differentiated.

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 real conditions: only an existing owner mandate is used, and reusing an operation_id requires identical text. It also says uncertain or accepted operations return state without sending, which tells the agent when calling is safe. There is no explicit 'use X instead' routing to a4a_dialogue_lease or a4a_send_private, so it falls just short of a 5.

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

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

With no annotations, the description carries the behavioral burden and does useful work: it states that already-published copies remain untouched, that private messages are not deleted, and that an in-flight send returns an error. It does not mention permissions, reversibility, or other side effects, but the core mutation behavior is well disclosed.

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

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

The core action and scope are front-loaded in the first sentence, followed by useful exclusions and an error condition. The description is compact and every sentence adds operational meaning.

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

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

The output schema covers return values, and the description adequately explains the tool's side effects and limitations. The main remaining gap is that event_id is not explained at all, which is important for correct invocation but partly mitigated by there being only one required 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?

The schema has one required parameter, event_id, with 0% description coverage, and the description never mentions event_id or explains its expected format. 'One exact local public retry' only indirectly implies that the parameter identifies the retry, so the description does not compensate for the schema gap.

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

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

The description uses a specific verb, 'Cancel,' and a precisely scoped resource, 'one exact local public retry,' and it explicitly ties the operation to reviewing publication_status. It also distinguishes the action from adjacent operations by listing what it does not do.

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

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

It gives a clear usage condition by saying the tool is used after reviewing publication_status, and it supplies meaningful exclusions such as not withdrawing published copies or retrying a held authorization. It does not explicitly name a sibling alternative for repair or replacement cases, so it stops short of full when-to-use/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?

With no annotations, the description carries the burden well: it discloses the write side effect ('writes a `<path>.a4a` blob beside the file'), the crypto (ChaCha20-Poly1305, random per-file key), that the key is stored locally in ~/.a4a/file-keys.json and hidden from the response, and that only this machine can send the blob. It omits edge-case behavior (missing file, overwrite/refusal of existing .a4a) and permission needs, keeping it from a 5.

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

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

Front-loaded with purpose and workflow position, then mechanics, then args/returns – good structure. Minor waste: the 'Args' line largely restates the schema and the 'Returns' line largely restates the existing output schema, but both are brief.

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

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

For a one-parameter workflow step with an output schema already present, the description supplies everything an agent needs: the write side effect, crypto/key handling, the local-only sending constraint, and the exact follow-up calls. Return values needn't be explained given the output schema.

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

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

Schema coverage is 0%, so the description must compensate. It labels 'path' as the 'Source file path' and explains the derived output ('`<path>.a4a` blob beside the file'), giving real meaning to the single parameter beyond its bare name. Minor gap: no format/absolute-vs-relative guidance.

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 ('Encrypt a file') and immediately frames its position in a workflow ('step 1 of 3'), which distinguishes it from siblings like a4a_send_file and a4a_open_file. An agent can tell exactly what this tool does 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?

Explicitly names the next actions: upload the blob to https/ipfs/ar, use the returned sha256 for content-addressed storage, then call a4a_send_file(to_pubkey, blob_path, url, name, mime). It also states what the SDK does NOT do (upload), removing ambiguity about alternatives.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does useful work by describing the return fields (address, category, capabilities, profile text) and that None disables each filter, but it is silent on pagination, result limits, ordering, and any auth requirements for the search.

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

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

Front-loaded with the purpose and sibling contrast, then cleanly structured Args/Returns sections. The repeated 'None disables this filter' line is slightly redundant but genuinely useful for optional-filter semantics.

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

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

All three optional parameters are documented, an output schema exists and the description briefly summarizes the return shape, so an agent has what it needs to call correctly. Minor gaps are pagination/limits, which the output schema may partly cover but the description does not tie in.

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 must compensate, and it largely does: it enumerates the valid category values (development, design, marketing, etc.), gives an example capability ('seo') and an ISO language code ('ru'), and explains that None disables each filter. Only the capability parameter remains open-ended without a value list.

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 (find) and resource (agents on the A4A network by profile) and explicitly distinguishes itself from a4a_search_intents, which searches orders instead of providers. An agent can route between the two 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?

Explicitly says to use it 'to find whom to contact' and contrasts it with a4a_search_intents ('searches for ORDERS'). That is clear use-context with the key alternative named, though it lacks explicit when-not-to-use conditions or prerequisite notes.

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

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

No annotations are provided, so the description must carry behavioral weight. "View" establishes read-only semantics, and it discloses the returned fields (ID, counterparty, price, deadline, status), but it says nothing about which statuses are included (active only? completed/expired?), pagination, or authorization prerequisites beyond party membership.

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?

Purpose is front-loaded and the Args/Returns block is scannable, but the sentence "Before this tool existed, an agreement proposed to you could not be seen at all" is historical color that does not help an agent decide whether or how 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?

For a one-parameter read tool with an output schema, the essentials are covered: purpose, the filter, and scope of party membership. Missing are the status/lifetime scope of results and any routing relative to the many sibling retrieval tools, which leaves gaps for a domain with 40+ tools.

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

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

Schema coverage is 0%, so the description must document the single parameter, and it does: counterparty filters by pubkey and None returns all. That fully compensates for the undocumented schema field, though it doesn't clarify public-key formatting.

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 resource (agreements) with a precise scope: "in which this agent is a party." The added line about one party publishing and the other discovering it distinguishes it from creation-side siblings like a4a_make_agreement and a4a_cosign_agreement, 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?

The framing "the other discovers it here" implies this is the retrieval path for agreements proposed to you, but there is no explicit when-to-use guidance and no named alternative such as a4a_get_offers or a4a_get_tasks. 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?

No annotations are provided, so the description carries the full burden; it says 'View', implying a non-mutating read, and names the returned data. It does not disclose whether reading affects request state (e.g., marks as seen), whether any authority or identity is required, or whether the list is paginated or bounded.

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 lines with the action front-loaded, no filler. The 'Returns' block partly duplicates the existing output schema, which slightly reduces its value but does not bloat the definition.

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

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

This is a simple, zero-parameter read with an output schema already describing return values, so the description covers the essentials. The modest remaining gap is the absence of any note on auth/identity scope or how pending requests relate to a4a_accept_connection.

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 schema has nothing to explain and the baseline of 4 applies. The description correctly implies no input is needed to retrieve the caller's pending requests.

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 ('View incoming connection requests'), which distinguishes it from the outbound a4a_request_connection and the follow-up a4a_accept_connection. It stops short of naming those siblings explicitly, so the differentiation is implicit.

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

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

The phrase 'incoming' implies this is the read step before accepting a request, but the description never says when to call it versus a4a_accept_connection, a4a_request_connection, or a4a_inbox_status. Usage is inferred 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?

With no annotations present, the description carries the full burden and does so unusually well: it declares non-effects ('publishes nothing, reads no private mail, creates no profile'), discloses that 'the query is visible to the configured relay', and explains the trusted-issuer configuration. It also preempts over-interpretation by stating the output is not a fraud score, authorization, or proof of work, and that high scores do not remove unknown recovery history, devices, or controller information.

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?

Purpose is correctly front-loaded, but the caveat block is over-stuffed with overlapping disclaimers — 'NOT a fraud score, authorization, or proof of work', 'does not prove a unique identity or replace a current attestation-status check', and 'a high score does not remove these limitations' restate the same epistemic caution three times. Tightening these would improve signal density without losing meaning.

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

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

For a no-annotation, two-parameter tool, the description covers the essential burden: effects, privacy exposure, configuration prerequisites, coverage caveats, and data provenance ('event dates are signer claims'). An output schema exists, so return-value documentation is not required, though error/empty-result behavior and any latency or rate expectations are unspecified.

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 0%, so the description must supply all parameter meaning, and the Args block does: pubkey is documented as a hex public key and days as a claimed-date window bounded 1–365 with default 30. It lacks guidance on invalid input handling (out-of-range days, malformed pubkey) or whether days bounds the reviewer-activity sample, but the core semantics are covered.

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 counterparty evidence') and enumerates the payload (ratings, author concentration, frequency by claimed dates, signed agreements, reviewer sample). It does not explicitly name which sibling it differs from — a4a_get_reputation and a4a_check_authority overlap heavily — so an agent must infer the distinction from content rather than an explicit pointer.

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?

'before choosing a customer or provider' gives a clear situational trigger for invocation. However, it never names the alternative tools for adjacent needs (reputation lookup, authority check, attestation status) or states when not to call it, leaving the sibling boundary 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?

No annotations are provided, so the description carries the full burden. It does disclose the return shape (ID, price, ETA, author pubkey, text) and the empty-state behavior, and 'View' implies a read-only operation, but it never states permissions, identity requirements, ordering, or whether offers can be filtered by status.

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

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

Two short sentences in a clean Args/Returns layout, front-loaded with the scope statement. No filler or repeated 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 one-parameter read tool with an output schema present, the description covers scope, the argument's meaning, and the empty-result case. Minor gaps remain around ordering, pagination, and offer status, but nothing an agent needs in order 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 0%, so the description has to compensate for the single intent_id parameter. It explains that the ID selects 'the intent whose offers should be shown' and that non-owned intents are allowed, but gives no format or sourcing guidance for the ID, so the compensation is only partial.

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 (view offers) and clarifies the scope is any intent, not just the caller's own, which separates it from a4a_publish_offer. It stops short of naming a sibling alternative explicitly, so it is clear but not fully differentiated.

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 infers it should call this after publishing an intent to review bids. There is no explicit when-to-use/when-not guidance and no reference to a4a_publish_offer, a4a_get_agreements, or a4a_search_intents as alternatives.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses the trust-graph weighting rule (weight > 0.1), what 'trusted-review count' actually means, that completion is only a signed result event under an overdue agreement, and extensive limitations (no proof of delivery, independence, payment, key ownership, or protection against collusion). This is unusually rich behavioral context.

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

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

The description is front-loaded with the core purpose, then proceeds to semantics, limitations, and args. It is long but dense with non-redundant caveats necessary for a reputation tool. Some sentences are repetitive in phrasing ('it is not proof…', 'does not prove…'), keeping it from a perfect 5, but overall the length is justified by complexity.

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

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

Despite an output schema being present (which could offload return-value explanation), the description still summarizes the return contents—average rating, review-record count, trusted subset, agreements with signed result events, and limitations. Combined with its thorough parameter and limitation disclosure, an agent has everything needed to call and interpret the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate fully. It does: pubkey is described as the agent hex public key to check, and verified_only is explained in detail—true includes only reviews under two-signature deals with trust-graph weighting, false includes all reviews without agreement checks or weighting. Both parameters are covered with actionable semantics.

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

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

Description opens with a specific verb and resource: 'Read review ratings and result-event evidence for an agent public key.' An agent can immediately tell what the tool retrieves. However, it does not explicitly differentiate itself from related siblings such as a4a_get_counterparty_evidence or a4a_publish_review, so it falls short of a 5.

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

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

The description explains the default strict mode (two-signature agreements, trust-graph weighting) and the alternative mode (verified_only=false includes all reviews without agreement checks). This gives clear guidance on when to use each mode. It does not name or exclude sibling tools, so it is not a 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?

With no annotations, the description carries the burden and does disclose a genuinely non-obvious behavior: only events from agreement parties are surfaced, while the relay may return any matching event. It does not state pagination, ordering, or whether it is strictly read-only, leaving some behavioral gaps for an unannotated 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?

Front-loaded with the action, then the scoping rule, then args and returns in a conventional order. The sentence explaining relay vs. party authority is somewhat redundant with the preceding sentence, but the slight overshoot is defensible for a security-relevant scope rule.

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 the terse 'Returns: Results and their references' is sufficient. Both parameters are addressed and the party-authority filtering is stated; only minor gaps remain (pagination, error conditions, explicit read-only framing) for a tool with no annotations.

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

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

Schema coverage is 0%, so the description must compensate, and it does: agreement_id is identified as the agreement, and task_id is described with the critical null semantic ('None returns every task in the agreement') that the bare schema omits. Format/syntax details for the IDs are still missing.

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 ('View work results under an agreement'), which is clearly a read of recorded work outputs rather than task definitions. It does not explicitly distinguish itself from near-siblings like a4a_get_tasks or a4a_get_counterparty_evidence, so an agent still has to 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?

Usage is implied by the party-only constraint and the 'task_id None returns every task' note, which tells the agent the scope-control pattern. There is no explicit when-to-use / when-not-to-use guidance relative to a4a_get_tasks or a4a_get_counterparty_evidence.

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

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

No annotations are provided, so the description carries the burden; 'View' implies a read-only operation and the Returns block names the fields surfaced. It says nothing about permissions, result limits, ordering, or whether the list is paginated, which is a real gap for a query tool with zero annotation coverage.

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

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

Front-loaded with the core statement, then Args and Returns in two compact blocks. Every line carries information; the only waste is the docstring-style formatting wrapping.

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

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

With an output schema present, the description needn't enumerate return shape, and it still summarizes the returned fields. Parameter semantics and read-only intent are covered; only edge behavior (ordering, empty result, pagination) 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 0%, but the description compensates by explaining the single parameter: it filters by agreement, and None returns all. That null-default semantics is the key non-obvious behavior and it is stated explicitly.

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 ('View') and resource ('tasks') with an explicit scope qualifier ('assigned to YOU'), which separates it from siblings like a4a_send_task or a4a_update_task_status. It stops short of naming the nearest alternative (a4a_get_task_results), so it is clear but not fully differentiated.

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 by the 'assigned to YOU' scope — an agent can infer this is the read-your-inbox path. No explicit when-to-use versus a4a_get_task_results or a4a_inbox_status is given.

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

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

With no annotations, the description carries the full burden and does well: it discloses the two-phase ordering (local commit first, signed network ACK second), the partial-failure state (network_ack_state=pending), and the idempotent retry path. It omits what happens on a duplicate completion with a different status and says nothing about required authorization or the rest of the response shape.

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

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

Four short sentences, front-loaded with the action and its legal statuses before the protocol mechanics. Every sentence adds a distinct operational fact with no restatement of the name or 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 three-parameter mutation with no annotations and no output schema, the description covers ordering, partial failure, retry, and rejection cases, and it even names one response field. The unexplained seq parameter and the absence of any authorization or double-completion note are the remaining gaps.

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 must compensate, and it partially does: it names the two legal status values (processed/failed) not encoded as an enum in the schema, and explains lease_token's role in retrying only the ACK. The seq parameter is never mentioned and lease_token's provenance is unstated, leaving real gaps.

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 ('Complete a lease') and constrains the outcome ('status=processed or failed'), which is far more than a restatement of the name. It does not explicitly separate itself from the similarly named a4a_dialogue_complete or say the lease originates from a4a_inbox_next, so sibling differentiation is only implied by the word 'lease'.

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 when-to-retry guidance ('repeat the exact call with the same lease token to retry only the ACK') and two exclusions (expired leases rejected, unknown work must not be repeated silently). It never names an alternative tool, so an agent must infer that this pairs with a4a_inbox_next rather than a4a_dialogue_complete.

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

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

With no annotations, the description carries the full behavioral burden and does so: 300s lease duration, expired leases become unknown and are NOT auto-redelivered, receiver_unavailable means no receiver rather than empty inbox, and file references are replaced with safe placeholders with an opaque attachment handle. This is unusually rich disclosure of edge cases and 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?

Front-loads the core action in the first sentence, then layers critical caveats. Nearly every sentence earns its place, though the cluster of file-handling caveats makes it slightly dense 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?

For a zero-param, zero-annotation, no-output-schema tool, the description supplies everything needed to invoke and follow up correctly: lease semantics, completion handoff, failure semantics, file handling, and mode restriction. No essential context is missing.

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

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

The tool takes zero parameters and schema coverage is 100%, so there is nothing to disambiguate at the parameter level. Baseline of 4 applies; the description's mention of seq and lease_token refers to return values rather than inputs.

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 ('Lease'), a precise resource ('one authorized message'), and a scope limit ('for 300 seconds'). An agent can immediately tell this is the inbox polling/claiming primitive and distinguish it from sibling tools like a4a_inbox_status and a4a_inbox_complete.

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

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

Explicitly routes the agent: call a4a_inbox_complete only after processing, use a4a_open_file for attachments, and use a4a_dialogue_open instead when in dialogue mode. It also states when this tool is disabled, which is exactly the when-not guidance agents need.

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 must carry the behavioral burden. It usefully discloses that the tool is local-only ('this process's local queue') and returns no network text, and it warns that host_wake=unverified does not prove model wake-up. However, it omits whether the tool is read-only, what the response shape looks like, and any permission or side-effect information.

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 brief and front-loads the purpose in the first sentence, followed by two short caveats. Every sentence adds some value, though the host_wake note is dense and could be clearer without requiring knowledge of an unexplained field.

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?

Without an output schema or annotations, the description should explain more about what the returned state contains and how to interpret it. It names the state categories and one host_wake caveat, but leaves the agent guessing about the overall response structure and read-only nature.

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 parameter semantics are trivially satisfied. A baseline of 4 is appropriate because there are no arguments to misinterpret.

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 ('Show') and resource ('this process's local queue, receiver, and notification state'), making the diagnostic purpose clear. It does not explicitly distinguish itself from siblings like a4a_delivery_status or a4a_inbox_next, but the scope is concrete enough for an agent to understand what it does.

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

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

No guidance is given on when to use this tool versus alternatives such as a4a_delivery_status or a4a_inbox_next. The note about host_wake interpretation is an output caveat, not a usage directive, so the agent must infer when this status check is appropriate.

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

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

With no annotations, the description carries the burden well: it discloses that the call publishes a public event, adds only your signature, requires counterparty cosign for validity, and that the returned ID must be reused. The role-assignment rule (agent_a/agent_b derived from fetching the intent and offer events, with a fallback when neither is available) is unusually concrete. It stops short of stating permissions, failure modes, or idempotency/retry behavior for a state-mutating publish.

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 and the two-step model, then parameter/return blocks — a sound structure. The 2026-08-29 historical aside justifies itself only partially (it explains why cosigning exists), and could be trimmed to a clause without losing anything the agent needs.

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

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

For a 5-required-param state-mutating tool with no annotations, the description covers sequencing, role derivation, ID reuse, and even the return value (though an output schema already exists). Remaining gaps are authorization requirements and error/edge-case behavior, which matter for an irreversible publish.

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 0%, so the description must compensate, and the Args block lists all five parameters. Only two glosses add real meaning: 'deadline_days: Number of days from now until delivery' (relative to now) and 'peer_pubkey: Counterparty public key' (establishes role). The rest are near-tautologies — 'price: Agreed price' gives no currency or unit, and intent_id/offer_id provide no format guidance.

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 states a concrete verb and resource ('Make a deal ... by publishing an Agreement (kind 31004)') and immediately positions it as the first of two signing steps. It names the sibling tools involved (a4a_get_agreements, a4a_cosign_agreement), so an agent can distinguish it from 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?

Explicit sequencing guidance: 'This is the FIRST of two steps', the counterparty concludes via a4a_cosign_agreement, and 'Subsequent operations must use the NEW ID.' It also states the validity condition (a deal is valid only when both parties sign the same digest), which tells the agent when this call alone is insufficient.

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 reasonably well: "Show" signals a non-mutating read, and the note "does not verify the network, receiver, or agent wake-up path" discloses an important limitation beyond the obvious. It does not state prerequisites (e.g., that the agent must be configured with a relay) or explicitly promise no 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 purpose and usage guidance are front-loaded in two tight sentences. The trailing "Returns:" block is somewhat redundant given an output schema exists, but it is short and the caveat sentence earns its space.

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

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

For a zero-parameter read of the agent's own address, the description covers what it does, when to use it, what comes back, and one meaningful limitation. An output schema exists, so the return detail is extra rather than necessary — nothing an agent needs in order 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate — the baseline for a no-arg tool is 4. The schema is empty and fully consistent with the described behavior.

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: "Show this A4A agent's address (pubkey and apub)." An agent can immediately tell this is a read of its own identity, distinct from publishing tools like a4a_publish_profile. It stops short of naming a sibling or contrasting behavior, so it lands at 4 rather than 5.

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

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

Gives a concrete when-to-use: "Use this to give another agent or person a way to contact you directly (for example, in a QR code or by sharing the apub)." That is a clear context with a concrete example. No when-not-to-use condition or named alternative is given.

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

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

With zero annotations the description carries the whole burden and does so thoroughly: no network request in blob_path mode, gateway-only fetching in attachment mode, "nothing is opened or run," a no-overwrite guarantee for out_path, hidden reference metadata, and a refusal reason on failure. These are the side effects and safety constraints an agent actually needs before calling a decryption routine.

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 one-sentence purpose followed by Args and Returns blocks, which is the right structure for a four-parameter security-sensitive tool. A few clauses are near-redundant (the gateway-only statement and the "no other location is followed" sentence overlap), costing some tightness without obscuring the essentials.

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

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

For a no-annotation, zero-schema-coverage tool, the description supplies mode selection, provenance constraints, side-effect guarantees, and return semantics, and an output schema exists to carry the return shape details. An agent has everything needed to invoke it correctly on the first try.

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 0% and all four parameters are documented in prose with meaning beyond their names: the mutual exclusivity of blob_path/attachment, the A4A attachment handle format, the non-overwrite behavior of out_path, and the 30-day default search window for since_days. Only a minor ambiguity remains about whether since_days applies solely to attachment mode.

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 opener gives a specific verb pair (verify/decrypt, save) and specific resources (local blob, mailbox gateway attachment), and the two-mode structure makes it unambiguous what the tool does. It never names the natural siblings a4a_encrypt_file or a4a_send_file, so an agent must infer the inverse-operation relationship itself.

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?

"Give this or `attachment`, not both" is an explicit selection rule between the two modes, and each mode's provenance condition is stated (owner/trusted-host-supplied local blob vs. only this mailbox's gateway as recipient). What is missing is routing guidance against alternatives such as using a4a_encrypt_file for the reverse direction or a4a_read_private for non-file content.

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

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

No annotations are provided, so the description carries the behavioral-disclosure burden. It usefully states that the operation is local and does not publish or contact nodes, but it does not address permissions, whether inspection has any local side effects, or other operational constraints.

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

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

The definition is a single front-loaded sentence with no repetition. Both clauses earn their place by stating scope and the key side-effect 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 zero parameters and an output schema, the description need not explain return values, and it supplies the key local/no-contact boundary. It leaves ambiguity about how status inspection relates to repair/discard workflows, which matters for correct tool selection.

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

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

There are zero input parameters, so there is no parameter semantics to document and the empty schema is fully described. The baseline for a zero-parameter tool is 4.

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

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

The description states a specific verb, 'Inspect,' and a specific resource, 'local pending public copies,' and its negative clause distinguishes it from publishing/contact tools. It stops short of naming the closest sibling alternatives such as discard_publication or repair_publications, so it is clear but not fully sibling-differentiated.

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

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

It implies use for local inspection and explicitly excludes publishing or contacting nodes, which gives some routing guidance. However, it names no alternative tools or concrete when-to-use conditions, such as checking before repair or discard.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses that the text field is published in a public event, remains forever, cannot be deleted, and may identify a client indirectly. It also notes that omitting text is the safe default and that details can be shared privately.

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 appropriately front-loaded with purpose and discovery behavior before the parameter documentation. The Args section is long, but most of its length is justified by the privacy and permanence warnings for text and the need-label guidance.

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 complex: eight parameters, no annotations, 0% schema coverage, and a public/immutable publication side effect. The description covers both invocation semantics and the critical safety constraints, and since an output schema exists it need not fully document return values.

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% and the description fully compensates for all eight parameters. It lists allowed categories, gives examples and identity-safety guidance for need, warns about the permanence of text, explains budget bounds and currency default, defines deadline_days, lists intent_type values with the default, and specifies language as an ISO code.

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: publish a need (order or request) to the A4A network under the calling identity. It also distinguishes the publish action from discovery via a4a_search_intents and response via a4a_publish_offer.

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 explains the surrounding flow: others find the published need through search and respond with an offer, and private details can be sent via a4a_send_private. However, it does not explicitly state when not to use this tool or contrast it directly with all adjacent publication siblings such as a4a_publish_profile.

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 substantial work: it warns that text is published in a PUBLIC event, persists forever, and cannot be deleted, and it states the return value is the offer ID. It omits other behaviors an agent would want, such as whether publishing requires an authority check, whether an offer can be withdrawn, or whether calling twice creates duplicate offers.

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 one-line purpose, then args, then returns. The three-sentence warning on text is long but genuinely load-bearing given the irreversibility it describes; the rest is tight 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 an irreversible public-write tool with no annotations, the critical risk (permanent, unidentifiable-data leakage) is disclosed. Remaining gaps — authorization requirements, retraction path via a4a_discard_publication, and idempotency — are meaningful but secondary; the output schema already covers the return value that the description repeats.

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 0%, so the description must compensate, and it defines all four parameters: intent_id's origin, price's currency basis, eta_days' semantics, and text's risk profile. It does not specify valid ranges or whether price must be positive, leaving a small gap.

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 ('respond ... with an offer') and resource ('another agent's intent'), which cleanly separates it from a4a_publish_intent (authoring an intent) and a4a_get_offers (reading offers on one's own intent). The pointer to a4a_search_intents as the source of intent_id further anchors what it acts on.

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

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

It implies the workflow (find an intent via a4a_search_intents, then offer against it) and gives a strong do/don't for the text field. But it never states when to prefer this over a4a_publish_intent, whether an offer replaces a previous one, or what to do if rejected — no explicit alternatives or exclusions.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that the profile is public, that repeat calls replace the previous profile, and that the return value is an event ID. It omits authority/auth requirements, failure behavior, rate limits, and whether omitted optional fields clear existing profile data, leaving meaningful gaps for a mutation tool.

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

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

The description is front-loaded with the core action and then organized into Args and Returns sections. Every sentence adds useful context, especially the replaceable-event behavior and parameter semantics, with no wasted text.

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 the description does not need to fully explain return values. The description covers purpose, parameters, and replacement semantics, but for a mutation tool with no annotations it is missing important completeness around authorization, failure cases, and partial-update behavior.

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%, but the description compensates by documenting all three parameters with clear semantics. It provides example capability values, enumerates the allowed category values even though the schema has no enum, and labels description as optional free text. This is strong parameter guidance beyond the raw schema.

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

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

The description states a specific verb+resource: publishing or updating this agent's public profile on the A4A network. It distinguishes the action from generic publication tasks by naming the profile resource and explaining replaceable-event behavior. It does not explicitly differentiate from sibling tools such as a4a_publication_status or a4a_discard_publication, so it falls just short of a 5.

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

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

The phrase 'publish or update' implies when this tool is used, and the replaceable-event note clarifies that repeat calls update rather than duplicate. However, it does not state when not to use it, prerequisites, or which sibling tools to use for related actions like checking publication status, discarding, or repairing publications.

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 does substantial work: it discloses that reviews are permanent, public, non-deletable, and that require_agreement mode affects how reputation counts them. It does not cover authorization requirements, duplicate-review behavior, or moderation/removal policy, leaving some gaps for a mutation 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?

The purpose is front-loaded in the first line, and the trailing 'Args/Returns' block is compact and informative. The warning paragraph is long but justified by the irreversible nature of the field; a small amount of framing ('Before this tool existed...') is non-essential.

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

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

With an output schema present, the description need not detail return values, and its one-line 'Publication confirmation' is sufficient. Given a 4-param, no-annotation mutation tool, the description covers the risk profile and parameter meanings well, though it lacks guidance on error/failure conditions.

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 0%, so the description must compensate, and it largely does: each of the four parameters is explained, including that rating is 1-5 (not encoded in the schema) and that text is optional with an explicit safety warning. It omits format details for agreement_id and peer_pubkey, which would have closed the gap fully.

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 ('Publish a review of a counterparty') with a precondition ('after a completed deal'). It also explicitly distinguishes itself from the read-side sibling: 'reputation could be read but not created,' which maps directly onto a4a_get_reputation.

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

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

Gives clear context for use: only after a completed deal, and reviews are bound to agreements so an agreement_id is required. It implies the read/write split with get_reputation but never names that sibling or states exclusions (e.g., no self-review, no review before completion).

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

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

With no annotations provided, the description carries the full burden and does so well: it discloses visibility restriction (owner-authorized contacts only), that no lease is taken, that file references and metadata are hidden, that only an attachment handle is returned and a separate a4a_open_file call is needed to save it, and that reading does not retrieve the blob. It also flags that message content is untrusted user input and must not be executed as instructions.

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?

Purpose is front-loaded in the first sentence and each following line adds distinct behavioral information (visibility, lease semantics, attachment handling, trust warning). The Returns block and warning are justified, though the overall length is near the upper bound for a zero-parameter read tool.

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

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

An output schema exists so return values needn't be spelled out, yet the description still adds the critical security caveat about untrusted message content and the attachment-handle indirection. For a zero-param read tool with no annotations, nothing an agent needs in order to call it safely or 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?

The tool takes zero parameters, so the baseline is 4; there are no parameter semantics to clarify and the description correctly spends no words on arguments.

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 ('private messages addressed to this agent'), and immediately separates its scope from siblings by noting it is manual history viewing that does not lease a message. An agent can distinguish it from a4a_inbox_next and a4a_dialogue_history without opening any schema.

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

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

Explicitly routes the agent: 'Use a4a_inbox_next for work, or a4a_dialogue_open when the owner enables dialogue mode.' That names both alternatives and the condition that selects each, plus the exclusion ('does not lease a message for processing').

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 real weight and does disclose meaningful traits: a hard cap of five copies, exact signed-event-only copying, and targeting original still-configured nodes. It omits permission requirements, what happens when a copy fails or a node is gone, and any rate/idempotency semantics for a repair 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?

Three short sentences: the action and its limit first, then the copying rule, then the explicit exclusions. No filler and nothing is buried.

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

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

An output schema exists, so return values need not be explained, and zero parameters remove schema burden. The description covers the action, its limit, and its scope. What is still missing is failure/retry outcome behavior and authorization context, which matters for a repair tool.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-param tool applies. The description correctly implies the scope is derived from stored publication state rather than from arguments.

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 ('Retry') and resource ('due copies of already authorized public announcements'), which is far more precise than the sibling tools that only publish or discard publications. It does not explicitly contrast with a4a_publication_status, which an agent might also reach for when a publication looks stuck.

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

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

The description implies the trigger condition ('due copies') and enumerates what it does not do (profiles, requests, mandates, private messages, new addresses), which usefully scopes it away from publish/discard siblings. It never names a specific alternative tool or says when to check status instead of repairing.

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 discloses important behavior: no lease is needed, an expired lease or concurrent session does not block the answer, forwarded letters are answered to the original sender with original ids, and delivery/journaling/checks match a4a_deliver. It omits error behavior and what happens if the letter is unread or already answered, which keeps it below 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 description is front-loaded with the core action and then structured into short, purposeful paragraphs covering seq semantics, lease behavior, forwarding, delivery semantics, args, and returns. Every section adds information relevant to correct invocation.

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 an output schema, the description is largely complete: it explains the binding, preconditions, parameter meanings, forwarding behavior, and that returns follow a4a_deliver plus the bound letter. Missing error scenarios and the exact semantic of an already-answered letter are minor gaps.

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 0%, so the description must compensate and it does: `seq` is defined as the mailbox number shown by a4a_inbox_next, and `text` is defined as plaintext with automatic encryption and metadata wrapping. Both parameters gain meaning beyond their bare schema types, though the `seq` explanation could be slightly more explicit about what happens on an invalid or unread seq.

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: answer a received letter, with the answer carrying a signed reference back to the original. It distinguishes this from plain delivery by explaining that the tool binds the answer to the letter via sender, delivery_id, and inner_id, which an agent would not infer from the name 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?

It gives clear conditions for use: the target must be a received letter identified by `seq`, must have been read once, and does not require a lease. It also covers the forwarded-copy edge case explicitly, though it does not name alternative sibling tools such as a4a_deliver or a4a_send_private and when to prefer them.

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 does so: it discloses that requests are public kind 31022 events, warns against putting work or client details in the intro, and explains that authorization is separate from an incoming request. These are non-obvious, high-consequence traits 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?

The key scoping sentence is front-loaded and the rest is tight, with the privacy warning placed exactly where the intro parameter is described. The 'Returns' line is redundant given an output schema exists, a minor bit of waste.

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

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

Given no annotations but a present output schema, the description covers authorization, public visibility, and handshake semantics well. It does not mention how to observe or respond to incoming requests (e.g. the connection-requests/accept siblings), leaving the agent to infer the rest of the flow.

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 0%, so the description must compensate, and it largely does: peer_pubkey is defined as the public key of the agent to contact, and intro is bounded as a 'short introduction' with an explicit warning about what content is safe to include. Format/length guidance for the pubkey is still absent.

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 ('Request a connection with another agent') plus a sequencing cue ('before starting a conversation') that separates it from the dialogue_* tools. It never names the reciprocal sibling a4a_accept_connection, so sibling differentiation is implied rather than explicit.

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

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

Gives clear preconditions: the owner must have authorized contact in local policy, and incoming requests do not substitute for that. It also clarifies the handshake requires both parties to send requests, which tells the agent this is a mutual-initiation step. No explicit 'use X instead' exclusion is stated.

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

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

With no annotations, the description carries the full burden and does well: it discloses the return shape (ID, type, category, subject label, budget, deadline, description, author pubkey), the no-match behavior ('explanatory message'), and the non-obvious caution that empty descriptions are normal rather than a red flag. It does not mention pagination, result limits, or read-only semantics.

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 one sentence, then Args and Returns in a scannable structure. Every section earns its place, though the docstring-style layout is slightly verbose for two optional filters.

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 two-parameter read tool, the description covers filters, enumerations, null handling, return fields, empty-result behavior, and the recommended next step. Combined with the existing output schema, an agent has everything needed to call it and interpret results.

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

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

Schema coverage is 0%, so the description must compensate and it does: both filters are enumerated by value (seven categories, six intent types) and the null semantics are stated ('None disables this filter'). Nothing about the two parameters is left ambiguous.

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 line states a specific verb and resource ('Find needs (intents)') plus scope ('published by others on the A4A network'), which implicitly separates it from a4a_publish_intent. It stops short of naming a sibling or spelling out the read-only search framing explicitly, so it is clear but not maximally differentiated.

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 follow-up guidance: when an intent's description is empty, judge by label/budget/deadline and 'ask privately with a4a_send_private', naming the alternative tool. It does not state when not to use this search versus other discovery tools, but the context for use is clear.

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

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

With no annotations to fall back on, the description carries the entire behavioral burden and covers the irreversibility ('the key is loaded from local storage by blob sha256 and deleted after successful sending', which also explains why the same blob cannot be sent again). It also discloses who can see what: the relay sees only ciphertext, the storage provider sees only blob size, and the URL, filename, and key travel inside the encrypted message.

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 leads with the workflow position, then the irreversible key handoff, then Args, then Returns; no sentence is filler. The Returns line slightly duplicates the existing output schema and could be trimmed, but it is a single sentence and the overall shape stays tight.

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

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

For a 5-parameter mutation-style tool with no annotations, the definition supplies the workflow context, the exact destructive side effect, the privacy model, per-parameter meaning, and the failure shape. The output schema already covers return values, so nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description must define all 5 parameters, and it does: to_pubkey, blob_path (tied back to a4a_encrypt_file), name defaults, mime example, and a non-obvious url default. That url entry explains the three accepted schemes and what the empty default does, which no structured field conveys.

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?

It names the exact action (send an encrypted-file reference), places it in a numbered workflow (step 3 of 3, after uploading the blob), and points at the sibling tool that produces its input (a4a_encrypt_file). An agent can identify what this does and where it sits relative to a4a_encrypt_file and a4a_open_file 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?

It provides explicit preconditions (the blob must already be uploaded, with a reference to a4a_encrypt_file) and guidance for the optional url parameter to upload through the file gateway if left empty. It does not state exclusions such as when to use a4a_send_private or a4a_deliver instead, so it falls short of a full when-to-use/when-not-to-use statement.

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 well: it explains what the relay can and cannot see (sender and timestamp hidden by default gift-wrap, recipient necessarily visible), states encryption is automatic, and warns that the returned IDs are not a delivery receipt. This is exactly the behavioral context an agent needs for a write 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?

Front-loaded purpose sentence, then a compact prose paragraph on the privacy model, then clearly separated Args and Returns sections. Every sentence carries information; nothing 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?

Given no annotations, three properties at 0% schema coverage, and an existing output schema, the description covers purpose, privacy guarantees, all three parameters, and a critical caveat about the return value. 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 0%, so the description must compensate entirely, and it does: to_pubkey is specified as a hex public key, text as plaintext with automatic encryption, and conversation_id as an optional 64-character lowercase hex handle that is signed inside the gift wrap and never exposed to the relay. That adds substantial meaning beyond the bare schema types.

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 ('Send a private end-to-end encrypted message to another agent') and immediately clarifies a scope boundary by disclaiming anonymous forwarding. It does not, however, distinguish itself from closely related siblings such as a4a_dialogue_send, a4a_deliver, or a4a_reply, which also deliver messages.

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 privacy model ('private end-to-end encrypted' vs 'not anonymous forwarding'), giving an agent a rough sense of when this is appropriate. But there is no explicit when-to-use/when-not guidance and no named alternative among the many delivery-oriented siblings, so the agent must infer the routing decision.

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

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

With no annotations, the description carries the burden and does well: it discloses that description is published in a PUBLIC event, persists forever, cannot be deleted, and is especially risky post-deal. It also states the return value (task ID). It omits authority/permission requirements and any rate or on-chain cost behavior.

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?

Purpose is front-loaded and the Args/Returns structure is scannable. The description warning is slightly repetitive ('especially sensitive after a deal, when descriptions become detailed and enter both a tag and the event body'), which could be tightened without losing the safety signal.

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

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

For a 4-param mutation tool with no annotations, the definition covers the highest-risk behavior (irreversible public publishing) and the return value, which is redundant given the output schema but harmless. Missing pieces are authority prerequisites (a4a_check_authority) and what happens if the agreement is not concluded.

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 0%, so the description must compensate and does: each of the four parameters gets meaning — agreement_id provenance, executor as the counterparty pubkey, deadline_days as an offset from now, and description with its privacy semantics. This is meaningfully more than the schema's bare titles.

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 ('Assign a task') and constrains the scope to 'a concluded agreement', which distinguishes it from agreement-creation siblings like a4a_make_agreement. It does not explicitly name a sibling it is not, 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?

Gives a concrete when-not-to pattern for the description field and names the correct alternative ('Create the task without a description and send the brief through a4a_send_private'). The prerequisite that the agreement must already be concluded is stated, but there is no guidance on ordering against a4a_get_agreements or routing to a4a_get_tasks.

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

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

With no annotations, the description carries the full burden and does disclose a critical trait: submitted data is public, permanent, and cannot be deleted, plus a privacy caution about not identifying the client. It omits other behavior an agent would want — permissions required, what happens on resubmission, or whether submission is idempotent.

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

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

Purpose is front-loaded in the first line, followed by a compact per-argument list. The public/permanent warning is repeated for result_url and note, which is slightly redundant but defensible given the stakes.

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 the terse Returns line is acceptable. However, for a mutation tool with no annotations, the definition leaves gaps around authorization, prerequisite agreement state, resubmission behavior, and how the result relates to a4a_get_task_results.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: each of the four parameters is explained, with meaningful semantics for result_url (neutral, permanent, non-identifying) and note (optional, public, undeletable). Only task_id and agreement_id remain thin, described merely as identifiers with no format or source hints.

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 a task result, with named arguments. It does not distinguish itself from nearby siblings like a4a_deliver, a4a_send_file, or a4a_update_task_status, so the 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?

No guidance on when this should be used versus alternatives (e.g., a4a_deliver for delivering content, a4a_update_task_status for state changes), nor any stated preconditions such as requiring an existing agreement. Only field-content warnings are given.

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

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

With no annotations, the description carries the full behavioral burden and does add a valuable warning that 'note' is public, permanent, and cannot be deleted, while status and percentage remain visible without it. However, it does not disclose authority requirements, reversibility of status changes, or notification side effects beyond 'report ... to the customer.'

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 purpose, then uses compact Args and Returns sections with no redundant repetition of schema titles. Every sentence adds useful meaning, especially the public/permanent warning on note.

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 five-parameter mutation tool with no annotations, the description covers all parameters, allowed status values, note consequences, and return behavior, while the output schema already exists. The remaining gap is authority requirements or participant restrictions, which are not stated.

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 must compensate and does: it documents task_id's source from a4a_get_tasks, agreement_id's containing agreement, all five allowed status values, progress's 0-100 range, and note's optionality plus permanence warning.

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

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

The description uses the specific verb 'Report' with the resource 'task progress' and names the customer audience, so the core action is clear. It does not explicitly distinguish this from sibling tools such as a4a_submit_task_result, though it does reference a4a_get_tasks as the source of task_id.

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 'Report task progress to the customer' and the enumerated status values, but there is no explicit guidance on when to choose this tool versus a4a_submit_task_result or when status reporting is inappropriate. The status list gives some invocation context without explaining alternatives or exclusions.

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