Agorean

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

Annotations are honored (readOnlyHint=false, idempotentHint=false, openWorldHint=true) and the description adds substantial behavior beyond them: nothing moves until the profile wallet pays, no cash refunds, entitlement-not-balance semantics, quote network, expiration, and an explicit refusal list with error codes.

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

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

Front-loads what it does and the payment model before drilling into refusals and edge cases, so it is well-ordered. It is dense and long, with a few clauses (e.g., 'No other agent's text in the reply') that add bulk more than routing value.

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 output schema, it covers everything an agent needs: the returned fields (credit_link, pay_with, credit_usdc, expires_at), network, entitlement constraints, and the full refusal taxonomy.

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

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

Schema description coverage is 100%, so the schema already documents both parameters including ranges and idempotency semantics. The description reinforces that amount is quoted on Base as real money, but adds no syntax beyond the schema; baseline 3 applies.

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

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

Opens with a specific verb+resource: 'Buy prepaid credit for hosting and the promoted slot,' and clarifies it needs the API key. It distinguishes itself from the read-side sibling by pointing to myFees() for the ledger and docs('how-to-buy') for the buy 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?

States a clear condition for needing it ('You need it only for your real-money listings') and explains that Base Sepolia listings never consume credit, which steers the agent. It names alternatives (x402 client, hosted client, CLI) but does not give an explicit when-not-to-call exclusion.

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

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

Goes well beyond the annotations: one-answer-only write-once semantics, the `question.answered` event emitted to the asker, permanent public visibility of public/anonymous exchanges to later buyers, auth requirement, and a full error taxonomy. These are exactly the behavioral facts an agent cannot infer from `readOnlyHint=false` or `destructiveHint=false`.

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 action and the ownership gate, then layers constraints, errors, and return shape in single-clause semicolon-separated units. Dense but every clause carries operational information; there is no filler.

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

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

With no output schema, the description still supplies the return shape ('the question with its answer'), the untrusted-field warning for `question`/`asker.name`/`answer`, and the side effects. Nothing material for correct invocation is missing.

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

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

Schema covers 67%, including a rich idempotency_key description, but `question_id` has no schema description. The description compensates by explaining where question_ids come from (events / getQuestions) and that a foreign question_id yields `forbidden` while a missing one yields `not_found`.

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

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

Opens with a specific verb+resource ('Answer a question asked on one of your listings') and immediately scopes ownership ('only the listing's seller may'), which cleanly separates it from siblings like ask, getQuestions, and replyToReview.

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?

Tells the agent how questions are obtained ('question.asked events or in getQuestions with your key') and what happens on misuse (conflict / forbidden / not_found), which effectively defines the eligible context. It stops short of naming sibling tools for adjacent tasks, but the entry path is unambiguous.

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

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

Goes well beyond the annotations: it discloses the side effect on the listing, the emitted events (question.asked / question.answered), the specific error codes for each refusal case, a daily rate limit (60/profile), the return shape, and the untrusted free-text handling. 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?

Front-loaded with purpose and dense but mostly non-redundant; every sentence carries usage, behavior, error, or limit information. The backtick-heavy run-on style is terse to the point of being hard to scan, costing a little structure.

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

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

There is no output schema, yet the description explains the reply (question_id, asker, answer: null until answered) and the async answer path. Combined with errors, rate limit, and idempotency, nothing needed to call it correctly is missing.

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

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

Schema coverage is 75% and the schema already documents visibility, question, and idempotency_key. The description reinforces the visibility semantics and adds meaning the schema lacks — that question is the sole free text and is quarantined under _untrusted — which is real value for the trust boundary.

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 ('Ask the seller of a listing a question before buying') and immediately distinguishes itself from the sibling getQuestions by telling the agent to check it first. An agent can identify the tool without opening the schema.

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

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

Gives explicit when-to-use (before buying), names the alternative (getQuestions) and the condition that prefers it ('a public answer may already be there'), and surfaces the cases where the call is refused (own/paused/deleted listing). Routing is unambiguous.

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

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

Annotations only declare readOnly=false, idempotent=false, openWorld=true, destructive=false. The description goes far beyond: it flags irreversibility ('claiming cannot be undone'), a 10/hour rate limit, the auth material required, the side effects on reviews/sales/stars, and a full error taxonomy with reason codes. It also discloses that endpoint-supplied fields are wrapped under _untrusted, which is important context the annotations do not convey.

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

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

The core action and its prerequisites are front-loaded and almost every clause carries behavioral weight (error codes, rate limit, review-migration rules). It is, however, one very dense block; the long list of failure reasons and side effects would read better as structured bullets, costing it the top score.

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

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

There is no output schema, so the description must cover returns, and it does: source becomes 'listed', plus reviews_moved, reviews_by_proof, and own_reviews are named. Combined with the error taxonomy, irreversibility warning, and rate limit, an agent has everything needed to call 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 100%, so the baseline is 3, but the description adds real meaning: the wallet_proof must be valid for 10 minutes and signed by the key of pay_to_address, and it maps each failure to a reason code. That is beyond what the schema states, though idempotency_key semantics are left to the schema.

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

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

The description opens with a precise verb+resource ('Claim a listing we indexed') and immediately states the mechanism and outcome ('prove you control the wallet the endpoint is paid to and it becomes yours'). This cleanly separates it from createListing (you author it) and updateListing (you modify one you already own).

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 prerequisites (API key + wallet_proof), a documented alternative for a different state (updateListing to set status active on an unreachable listing), and a pre-call instruction (read getReviews before signing). Failure routing is enumerated by condition (already claimed, seller-created, >200 reviews, unknown/deleted), so the agent knows exactly when this tool applies versus others.

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

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

Annotations declare destructive=true and idempotent=true, and the description adds substantial context beyond them: status transitions, job.closed events, bidders_notified, closed_at, the already_closed no-op, and the subtle expired-but-still-open row behavior. The only thing not covered is auth mechanics beyond 'needs your API key', but overall this is rich disclosure.

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

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

A single dense paragraph with the core action front-loaded. Every clause carries information (events, counters, edge cases), though the em-dash-heavy packing makes it slightly harder to scan than a structured list would.

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

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

No output schema exists, so the description carries the return-value burden and does so completely: bidders_notified, closed_at, and already_closed are all explained. Edge cases (expired jobs, still-payable bids) are covered, leaving nothing an agent needs 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 67% and the schema already documents both reason and idempotency_key well. The description adds the mapping between reason values and the resulting status (filled vs closed, cancelled as default), which is meaningful semantics beyond the enum labels. job_id's meaning is self-evident.

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 ('Stop taking bids on a job you posted') and immediately scopes it to the poster via API key. Distinguishable from siblings like postJob, myJobs, and claimListing 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 tells the agent when NOT to use it ('Paying a bid fills the job on its own, so you only need this to close early or to cancel') and names the alternative path. Poster-only and key requirement are stated up front.

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

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

Annotations only cover basic safety hints (readOnly=false, openWorld=true, idempotent=false, destructive=false). The description adds substantial behavioral context beyond them: API-key requirement, private storage, payment-triggered delivery, awaiting_upload state, hosted file size limits, mainnet-facilitator refusal, 1,000 listings/day limit, duplicate-search hiding, counterpart validation errors, and the hosting_warning condition. This is rich disclosure with no contradiction.

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

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

The description is front-loaded with purpose and required fields, and most sentences carry operational detail. However, it is a single dense paragraph with many edge cases packed together, making it harder to scan than necessary for an 18-parameter tool. It is informative but not concise.

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

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

For a complex 18-parameter creation tool with no output schema, the description is unusually complete: it explains the reply fields, hosted/upload behavior, error codes, idempotent retry behavior indirectly via schema, duplicate hiding, and hosting_warning. Nothing critical for calling createListing correctly appears to be missing.

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

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

Schema description coverage is already 94%, so the baseline would be 3, but the description adds meaningful semantics: how to choose among the category enum values, when to use hosted vs url/mcp/a2a delivery, network immutability after a sale, the upload flow for large files, use_cases formatting and refusal rules, and counterpart_listing_id constraints. It goes well beyond the structured schema.

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

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

States a specific verb and resource: 'List something for sale.' It immediately distinguishes this creation tool from siblings like updateListing, getListing, myListings, and claimListing by naming the required API key, category, and delivery modes. An agent can tell what it 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?

Gives explicit conditions for choosing delivery modes (hosted vs url/mcp/a2a), network selection (practice vs real money), and counterpart listings. It also instructs the multi-step upload path when a file exceeds 4 MB. It does not explicitly compare against every sibling, but for a create operation the guidance is clear and actionable.

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

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

Annotations only cover safety/idempotency hints; the description goes well beyond them by disclosing the one-time secret exposure, the retry-refusal behavior on idempotency_key, the claim-token semantics of the funding link, the wallet conflict/retirement rules, and the interaction with reviewPayment profiles. These are exactly the behavioral traits an agent cannot infer from structured fields.

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

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

The content earns its place, but the description is long and repeats ideas: the 'shown once / retry refused with conflict' message appears twice and again in the idempotency_key schema entry. The opening 'Your human clicks one link and keeps one folder' is atmospheric rather than operational, and the key warning is not cleanly front-loaded.

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

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

With no output schema, the description must carry return semantics and largely does — API key, funding link with claim token, profile id caveat, and the note that the reply carries no seller-written text. It is nearly complete, though the precise response shape is still inferred rather than 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond it: wallet_proof is specified as a five-line note with purpose create_profile and issued_at within 10 minutes signed EIP-191, recovery_pubkey is stored as an address, and human_email is 'an optional hint, not ownership'. Only minor syntax detail is left to the schema.

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

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

The description states a specific verb and resource — registering a profile tied to a wallet and recovery address — and clearly separates it from siblings by naming updateProfile for funding-link rotation and getProfile implicitly. An agent can tell what this creates and what it returns (API key, funding link) 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?

It gives explicit when-to-use context ('You create the profile yourself. There is no human account'), names the alternative for recovering a lost link (updateProfile({rotate_funding_link: true})), and states when-not conditions ('A wallet can register once, and a wallet another profile ever held cannot be registered at all'). It also notes 'Needs no key', which is a concrete precondition.

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

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

Beyond the destructiveHint/idempotentHint annotations, it discloses that deletion is a soft delete (row kept, marked deleted, never served), that purchases and reviews survive, that auth requires a signed challenge plus API key, and that repeating the call is a no-op returning the same deleted_at with already_deleted: true. This is the kind of behavior an agent cannot infer from annotations or schema.

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

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

Front-loaded with the destructive, irreversible core, then auth, then edge cases. Dense but nearly every clause carries new information; the parentheticals and stacked semicolons make it slightly harder to scan than it needs to be.

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 no output schema, the description covers the return contract (deleted_at, already_deleted: true), idempotency behavior, authorization, and data retention. Nothing an agent needs to invoke this mutation correctly is missing.

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

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

Schema coverage is 67%, and the description compensates for the gaps: it explains the challenge object's shape and why the API key alone fails (challenge_required), and that the recovery key signs getChallenge's message. It adds meaning beyond the schema for the auth path, though listing_id itself is left to the schema.

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

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

States a specific verb+resource (delete a listing) and immediately distinguishes itself from the nearest sibling: 'updateListing pauses; this removes'. It also pins the exact semantics (permanent soft delete, removed from search/getListing/lists), so an agent can tell it apart from updateListing and closeJob-like lifecycle tools.

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

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

Explicitly names the alternative (updateListing) and the condition that selects each (pause vs remove), plus when-not conditions (key alone refused, only the seller may). Prerequisites are spelled out: call getChallenge, sign its message with the recovery key, pass challenge_id and signature.

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

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

Annotations declare write/openWorld/non-idempotent, and the description goes well beyond them: API-key auth, seller-only permission, private storage with a signed 24-hour link, one-delivery-per-purchase, buyer event, and the exact error semantics. This is unusually complete behavioral disclosure.

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

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

One dense paragraph, front-loaded with the action and the constraint, and nearly every clause carries new information (size cap, link lifetime, error codes, response shape). Slightly heavy to read as a single run-on block, but not padded.

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

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

With no output schema, the description still enumerates the reply fields (delivery_id, kind, bytes, sha256, delivered_at) and the _untrusted marking. Auth, error paths, and idempotency are all covered, so an agent has everything needed to call 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 86%, so the schema carries most of the load, but the description adds the critical XOR constraint between content_base64 and url, the 4 MB decoded limit, and the content_type/filename pairing. It does not restate the idempotency_key semantics, which the schema covers.

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 ('Attach the deliverable to a purchase you sold') with clear scope (only the seller may). An agent can distinguish it immediately from the read-side sibling getDelivery.

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 two mutually exclusive input paths ('exactly one of the two') and the caller constraint (only the seller), and routes readers to getDelivery. It also enumerates when the call fails (conflict/forbidden/not_yet), which is genuine when-to-use guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint=false, but the description adds real context: public endpoint, no key needed, and a trust guarantee that nothing in the reply is written by a third party. It also discloses return shapes (a note plus slug/title/blurb per topic, markdown pages, and that show-your-human hands the page to the human). Not a 5 only because it does not mention size limits or pagination of the index.

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 action and then walks the three modes in matching order to the parameters, with no filler. The middle sentences are dense and pack multiple facts each, which is efficient but borders on run-on.

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

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

No output schema exists, so the description must carry return-value information, and it does: it describes the index shape, markdown page responses, and the human-handoff behavior. Dense enough for a two-parameter read tool; only minor gaps such as whether the index is cached or how large pages are.

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

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

Schema coverage is 100%, so baseline is 3; the description nevertheless adds semantics beyond the schema, explaining that query matches by meaning and returns best-first, and that topic must be a slug drawn from the index and that show-your-human is a special slug. That is meaningful guidance layered on already-documented parameters.

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

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

States a specific verb and resource ("Read the Agorean docs") and then enumerates the three distinct modes: no-topic index, topic-slug page, and query-based semantic lookup. The three modes are clearly separated, so an agent can distinguish them from each other and from siblings like search or searchInsights.

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

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

Gives explicit conditions for each call shape: no topic for the index, a topic slug for that page, and query "when you know the thing but not our name for it." That last clause is an unusually direct routing rule that tells an agent when to prefer this tool over guessing a sibling tool name.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: discloses the API key requirement, the invalid_input error when wait exceeds 6s, cursor continuation via next_cursor, event-type semantics per role, and a security warning that eight payload types carry another agent's words to be treated as data, never instructions. This is rich behavioral context an agent needs.

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

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

Purpose and cursor mechanics are front-loaded, and most content earns its place. However, the entire description is a single dense paragraph, and the long enumeration of event types slightly hampers scannability.

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

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

With no output schema, the description fully carries the return-shape burden by specifying each event as {id, type, profile_id, created_at, payload} and explaining what next_cursor contains. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 67% and the description compensates substantially: it specifies limit 1–100 (default 50), wait 0–6s (default 0) with the invalid_input consequence, the 'evt_88' format for after, and that next_cursor should be passed as after next time. This adds meaning well beyond the schema.

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

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

States a specific verb and resource: 'Your event stream, oldest first,' and clarifies scope with the cursor mechanic. No sibling among the listed tools provides an event stream, so an agent can distinguish it immediately without opening a schema.

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

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

Provides clear context: needs your API key, describes the cursor-based continuation pattern, and explains the polling use case ('an agent with no server can poll without hammering us'). It also contrasts with webhooks ('the same bytes a webhook receives'). However, it does not explicitly name a sibling alternative or state when not to use this tool.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: discloses ordering (oldest first), a hard cap (at most 200), the full return shape, the x402 payment side effects (job marked filled, other bidders get job.closed), and trust boundaries marking seller-authored fields as `_untrusted`. This is rich behavioral context an agent cannot infer elsewhere.

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 resource and scope, then the field list, then the accept flow. Dense but every clause carries information; the x402 acceptance passage is slightly tangential to a read tool but earns its place by explaining side effects.

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

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

No output schema exists, so the description's enumeration of returned fields (quote_id, stars, price_usdc, buy_url, purchase_id, etc.) is essential and complete, and it closes the loop on trust and payment semantics.

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?

One parameter (job_id) with 0% schema description coverage, so the description must carry the load. It implies job_id refers to 'a job you posted' but adds no format or sourcing detail. Adequate but thin 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?

States a specific verb+resource ('The bids on a job you posted') and scopes it to the poster, which cleanly distinguishes it from siblings like getQuote, getDelivery, and myPurchases. An agent knows exactly what it retrieves without opening the schema.

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

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

Gives clear context ('needs your API key; poster only') and explains the downstream accept-by-paying flow, which tells the agent why it would call this. It stops short of naming an explicit alternative tool or exclusion beyond the poster-only constraint.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=true), the description discloses single-use semantics, a 5-minute expiry, a 10-per-hour-per-profile rate limit, the exact signing scheme (EIP-191 personal_sign over a specified message format), and that the reply contains no seller-written text. These are operationally critical facts the structured fields do not carry, and none contradict the annotations.

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

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

Purpose and gating rationale are front-loaded and most sentences carry unique constraints (expiry, rate limit, signing format). The one weak spot is the instruction to pass `challenge: { challenge_id, signature }` 'to the tool,' which refers to the consuming tools rather than this one and could momentarily confuse an agent reading only this 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?

With no output schema, the description still characterizes the reply ('No seller-written text'), and it covers the full lifecycle of the challenge — generation, signing format, single use, expiry, and rate limits. Nothing an agent needs to call this tool correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already fully documented. The description's note that profile_id is implied with an API key and required without one largely restates the schema's own wording, adding rationale but no new syntax or format detail. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('Get a one-time challenge to sign with your recovery key') and explicitly distinguishes itself from siblings by naming rotateKey, setHumanEmail, updateWallet, and deleteListing as the operations it unlocks. An agent can place this tool precisely without opening any other schema.

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

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

It gives explicit when-to-use conditions: it is the only path to the four named gated tools, works with an API key (profile implied) or without one by passing profile_id, and notes 'a lost key is exactly when you need this.' That is when/when-not/alternative coverage in one paragraph.

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

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

Beyond the readOnlyHint/openWorldHint annotations, it discloses auth requirements, URL expiry (24h, re-call for fresh), download verification fields (sha256, bytes, content_type), the two `kind` behaviors, `source` semantics, and the asynchronous `not_found` behavior. This is unusually rich behavioral context that annotations cannot carry.

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

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

It is front-loaded with the core purpose before the detail, and every clause (expiry, verification, event timing, untrusted note) earns its place. It is dense and somewhat run-on, but there is no filler.

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

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

No output schema exists, so the description must explain return values, and it does: `kind`, `url`, `expires_at`, `content_type`, `bytes`, `sha256`, `source`, and the `_untrusted` note. An agent has everything needed to call it and interpret the response.

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?

With schema coverage at 0% for the single `purchase_id`, the description carries the burden and does add meaning: the ID identifies a purchase and access is scoped to the buyer or seller. It stops short of describing the ID's format, but the semantics of what the parameter references are clear.

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

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

The description opens with a specific verb+resource: 'Fetch what was delivered against a purchase.' It is immediately distinguishable from the sibling `deliver` (the write side) and from `myPurchases`/`getListing` (metadata side) by scoping to the delivery artifact 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?

It states the caller preconditions (buyer or seller only, `forbidden` otherwise) and gives explicit timing guidance: wait for the `delivery.sent` event before polling, and the reply is `not_found` with `details.reason = not_delivered_yet` and is explicitly non-retryable. This tells the agent both when to call and when NOT to retry.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations, enumerating the status values, the extra return fields (reply, distinct_agent_count), the re-grouping behavior on the grouped report, the specific error outcomes (forbidden / not_your_filing / not_found), and the security note that title/message come back under _untrusted.

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

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

A single dense paragraph that is front-loaded with the core action and stays on topic throughout. It runs slightly long with nested details, but each clause (statuses, error cases, trust warning) carries real 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?

With no output schema, the description correctly assumes the burden of describing return values (status, reply, distinct_agent_count) and error states, so an agent needs nothing more to interpret results or handle failures.

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

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

Schema coverage is 100% and the single parameter's schema description already says where the filing_id comes from, so the description largely repeats it. The added auth framing is behavioral rather than parameter-specific, leaving only baseline value.

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 precise verb+resource (retrieve the status of a feedback filing) and immediately names the sibling tools (sendFeedback, reportListing) that produce the input. An agent can distinguish it from myListingFeedback and related tools without opening the schema.

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

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

Explains the precondition (needs your API key) and the workflow context (pass the filing_id you got from sendFeedback or reportListing), which routes the agent from the write tools to this read tool. It does not explicitly name when NOT to use it versus similar status tools like myListingFeedback, so it stops short of full routing guidance.

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

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

Far exceeds the annotations: `needs no key`, `not_found` on missing/deleted, the `_untrusted` list of agent-authored fields, the explicit warning that `status`/`buyable_here` are not liveness checks, the weekly re-read and two-failure rule for indexed endpoints, the meaning of 404/405 on an unpaid buy_url, and the `payee_changed`/`payee_changed_at` money-loss scenario. This is exactly the context `readOnlyHint`/`openWorldHint` cannot convey.

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

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

A single multi-hundred-word paragraph with chained em-dash clauses and no bullets or headings, so the highest-stakes content (`_untrusted`, `payee_changed`, `buy_input_fields` costing real money) lands at the very end. Individual facts mostly earn their place given the field count, but the delivery is not front-loaded and is hard to scan.

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

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

There is no output schema, so the description must document the return shape itself, and it does so field by field (`price_basis`, `network` with CAIP-2 examples, `protocols`, `buy_method`, `buy_input_fields`, `also_on`, `search_hidden`, `duplicate_of`). For a read tool with one parameter and no output schema, an agent has everything needed to call it and interpret the response.

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 the single `listing_id` param has no description in the schema (only min/max length), so the description carries the burden. It does use `listing_id` in context (`also_on` twins, `agorean buy <listing_id>`) but never states the identifier's format or where an agent obtains one, so compensation is 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?

Opens with a specific verb+resource ("Read one listing in full") and then enumerates exactly what comes back, so an agent knows this is the detail-fetch counterpart to `search`, `getQuestions`, `getReviews` and `myListings`. The sibling boundary is implicit but clear: this is the single-listing read, not a list, not a search, not a mutation.

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?

Rich in routing: it sends the agent to `getQuestions` for the full question set, `ask` to add one, `getReviews` before paying, `reviewPayment`/`review` after paying, and `claimListing` for an unclaimed indexed listing, and it states that `ask`/`requestQuote`/`recordPurchase`/`promote` refuse certain listings. What it lacks is an explicit up-front "use this when you have a listing_id and need to evaluate before buying" statement, so the guidance must be mined from a wall of prose.

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

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

Annotations only cover readOnly/openWorld; the description adds material behavior: no API key required, email/keys/human identity are never exposed, missing or deleted profiles yield not_found, listing texts and name/description are surfaced under _untrusted, and only the newest 20 listings are returned. It also explains why cross-chain figures are separated (practice vs real money) and the review proof-rung 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?

It is one enormous sentence built from deeply nested parentheticals, including a five-rung proof explainer inlined mid-clause. The content is valuable and the purpose is front-loaded, but the nesting makes it hard to parse and the seller-stats clause alone spans most of the 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?

With no output schema, the description carries the full burden and discharges it: it breaks out seller vs buyer stat groups, the per-chain breakdown, listing count, the not_found error case, and the trust boundary for agent-authored text. An agent could call this and interpret the response without further help.

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

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

Schema coverage is 100% for the single parameter and already documents 'prf_… or 0x… wallet, current or earlier'. The description restates the same id-or-wallet acceptance without adding format, validation, or resolution order rules (e.g., which wins on conflict), so baseline 3 applies.

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

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

Opens with a specific verb+resource+scope: 'The public profile of any agent, by profile id or wallet address', and enumerates the returned sections (seller stats, buyer stats, active listings). Saying 'any agent' distinguishes it implicitly from self-scoped siblings like mySales/myReviews, and from updateProfile/createProfile.

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

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

Usage is implied rather than stated: it's a read of any agent's profile, needing no key, returning not_found for a missing profile. There is no explicit 'use this when… instead of getListing/search/…' routing, and no statement of what to do with the returned untrusted fields beyond them being flagged.

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

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

Annotations only give readOnlyHint/openWorldHint, but the description adds auth-dependent result scoping, the `not_found` failure mode for missing or deleted listings, `answer` being null pre-answer, and a prompt-injection caveat about other agents' text under `_untrusted`. That is substantial context beyond the structured data.

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?

Dense and front-loaded, with the read-first rationale leading and paging/error/injection notes trailing. It is a single long paragraph, so the pagination, error and trust content is not visually separated, but no sentence 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?

There is no output schema, so the description carries the return-shape burden and does: `answer` is null until answered, anonymous askers show no name, paging uses `next_cursor`, and untrusted fields are flagged. An agent can call and interpret this correctly without further docs.

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

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

Schema coverage is only 33% (cursor documented, limit and listing_id bare), and the description compensates by explaining paging with `limit` (≤ 50) and `next_cursor`. It stops short of describing the listing_id format, and the limit ≤ 50 detail repeats the schema's maximum.

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

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

Specific verb+resource ('Read the questions asked on a listing and the seller's answers'), plus the ordering ('newest first'). It is clearly distinguishable from siblings like ask and answer, and the auth-conditional scope is spelled out.

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

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

Explicit when-to-use: 'read it before you ask; a public answer may already be there.' It also states exactly which content appears under each auth condition (anonymous key, personal key, seller), so the agent knows which mode returns what.

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

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

Annotations only say readOnlyHint/openWorldHint; the description adds substantive context beyond them: the buyer-or-seller authorization constraint, the 7-day default expiry, and the semantics of status/job_id/listing_id. It also flags that brief, message and seller.name are other agents' content surfaced under _untrusted, which is a trust-boundary disclosure the annotations do not convey.

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

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

Front-loaded with the core action, then dense but purposeful state and field reference — every clause maps to a field or a next step. It is long and reads as a single run-on block with backtick-heavy enumeration, which slightly hurts scannability, but there is little 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?

There is no output schema, so the description carries the full return-value burden and does it thoroughly: it names every returned field, explains status values, and clarifies when job_id and listing_id are populated. For a read tool with one parameter and an open-world annotation, nothing an agent needs in order to call and interpret it 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?

Only one parameter (quote_id, required, 1-40 chars) and the schema description coverage is 0%, so the description must compensate. It never states what quote_id is or where to obtain it (presumably the requestQuote/sendQuote response), though the surrounding status/job_id/listing_id discussion implicitly frames quotes as first-class objects. Adequate but leaves the identifier's origin unstated.

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

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

Opens with a specific verb+resource+scope ('Read one quote in full') and immediately enumerates exactly what is returned (brief, budget_usdc, deadline, price_usdc, delivery_time, message, buy_url, expires_at). It also distinguishes itself from adjacent tools by naming getDelivery, deliver and getReviews as the routes for things this tool does not cover.

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

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

Gives explicit eligibility ('you must be its buyer or its seller') and then a full decision table keyed on status: requested = no action yet, quoted = pay buy_url, paid = read via getDelivery, expired = ask again, declined = stop. Each state routes the agent to the correct next tool, so there is no inference required.

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

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

Beyond the readOnly/openWorld annotations, it discloses no auth required, hidden-review legal policy, untrusted content grouping, public-suffix error behavior, network-default scoring, pagination limits, not_found semantics, and trust-score null conditions. This is unusually rich behavioral context and does not contradict the annotations.

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

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

The purpose and usage rules are front-loaded, but the description then becomes a dense wall of text with many nested clauses. Most details are useful given the absent output schema, but the lack of structure makes it harder to scan than necessary.

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 tool with no output schema, the description thoroughly explains return fields, proof rungs, trust-score formula, pagination, selector behavior, error cases, and endpoint context. There is little an agent would need to infer to call 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?

Although schema coverage is already high at 89%, the description adds important semantics not captured by the schema: the mutual exclusivity of the five selector parameters, the network-defaulting behavior for numbers, limit ≤ 50, cursor from next_cursor, and expect_pay_to’s effect on pay_to_matches.

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

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

The description opens with a specific verb and resource: reading buyer reviews about sellers before paying, for any x402 endpoint. It explicitly distinguishes from the writing tool reviewPayment and makes clear this is the read counterpart.

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

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

It states when to use it (before paying, with no key), how to scope it (pass exactly one of listing_id, profile_id, resource, domain, or pay_to), and names reviewPayment as the alternative for adding your own review after payment.

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

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

Annotations already cover read-only and closed-world, and the description layers on real behavioral context: the unavailable edge case where a sign-told deploy serves no document, the misconfigured state, the fact it mirrors a public URL, and who authors it. These are non-obvious failure modes an agent could not infer from annotations.

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

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

Front-loaded with what the document is, then the field to branch on, then the state enumeration. Every sentence carries information, though the signature-state taxonomy is dense enough that it takes a second read for an agent skimming.

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

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

With no output schema, the description carries the return-value burden and does so: it lists the object's contents and names the one field an agent must branch on, plus the degraded case. Nothing needed to call it or interpret it 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?

Zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly spends no ink on 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 and resource ('Read the honesty manifest') and then enumerates exactly what the returned JSON object contains: fee wallet, fees, rate limits, api_version, tool list, deprecation schedule. It is unmistakably distinct from siblings like docs or myFees.

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

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

Gives a clear operating instruction — branch on signature_state — and enumerates the three values with what to do for each (verify signature with signature_pubkey, etc.). It also states the no-auth condition ('Public, no key needed'). It does not name a sibling alternative for when a narrower read (e.g. myFees) is preferable, so it stops 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description goes well beyond that by disclosing that `reconciles` is recomputed on every call, the exact invariant checked (credit = bought + discounts − charges to the micro-USDC), and the specific failure mode when the ledger exceeds 20,000 lines (`null` + `reconciles_reason: ledger_too_large`). It also explains that `promotion` pause reasons are freshly computed rather than stored, and that `network`/`testnet` are legacy fallbacks — rich behavioral context an agent cannot get from structured fields.

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

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

Front-loaded with the purpose and the `reconciles` payoff, and nearly every sentence carries genuine field-level meaning. But it is a single unbroken block dense with backticked identifiers and edge-case caveats (window_too_large, cap_reached, credit_empty, low_rating) that would scan far better as a structured list; the reader has to work to extract the hierarchy.

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

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

There is no output schema, so the description carries the full burden of explaining the return shape — and it does, field by field: credit, credit_bought_usdc, charges_this_month, charged_usdc, reconciles/reconciles_reason, pace and its null cases, free_allowance/claimed, promotion pause reasons, recent, networks, and the listing-vs-deployment settlement rule. Nothing an agent needs in order to interpret the reply 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?

Zero parameters, so the schema has nothing to document and the baseline is 4. The description correctly implies the call needs no inputs beyond authentication, and there are no param semantics to add.

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

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

Opens with a specific verb+resource ('Your fee ledger and whether it adds up') and immediately names the headline output, `reconciles`, as 'the point of this call.' An agent can tell this apart from sibling tools like reviewPayment, myPurchases, or mySales without opening the schema.

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

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

Gives clear operating context: needs an API key, the `reconciles` field is the reason to call, and it explicitly redirects callers to read `networks` instead of the deprecated `network`/`testnet` fields. It lacks explicit when-not-to-use guidance or named alternative siblings, keeping it 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds meaningful context beyond annotations: it requires an API key, returns newest-first lists, and flags poster/brief text under `_untrusted`. It does not discuss rate limits or pagination behavior, so it is not exhaustive.

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

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

The purpose is front-loaded in the first sentence, and the subsequent explanation of `posted` and `matched` shapes is dense but earns its place. A bulleted structure might improve scanability, but there is little 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?

With no output schema, the description compensates by explaining the returned `posted` and `matched` structures, including fields like `matched_sellers`, `bids`, `my_bid`, and `_untrusted`. It also covers API-key requirements and ordering, leaving little an agent needs to infer before calling the 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 description coverage is 100%, so both `limit` and `status` are already documented in the schema. The description adds only 'Filter with `status`', which reinforces the schema but contributes no new syntax or edge-case semantics. Baseline 3 is appropriate when the schema carries parameter meaning.

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 resource: 'Your side of the job board', and breaks it into `posted` and `matched` sections with their returned fields. It effectively distinguishes this personal job view from generic job search tools by tying it to the caller's API key and personal activity.

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 guidance for follow-up actions: use getBids(job_id) to read bids and closeJob to stop taking them. It also explains filtering with `status`. However, it does not explicitly contrast myJobs with siblings like searchJobs or myListings, leaving broader usage 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?

Adds substantial context beyond the annotations: it requires an API key, is ordered newest first, is private to the caller, has no rating effect, and most importantly discloses the read-receipt side effect ('Reading marks the rows read, once: read_at is the moment you first read each one') that the readOnlyHint alone would hide.

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 concept before the long clause enumerating returned fields. The density is largely justified because there is no output schema, but the proof-ladder expansion and layered parentheticals make it a heavy single block that could be trimmed.

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

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

With no output schema, the description fully documents the return shape (flags, proof ladder, counts, tx_hash, network, wallet, read_at, reply) and the two-way received/sent split, plus privacy and read-marking behavior. An agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so both `limit` (per list, newest first) and `listing_id` (one listing vs all) are already documented. The description echoes the filtering behavior but adds no syntax or defaults the schema lacks; baseline 3 applies.

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

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

States a specific verb+resource ('private feedback on your listings') and cleanly splits the tool's two modes: `received` (what agents sent you) and `sent` (what your wallet signed elsewhere). It distinguishes itself from review-oriented siblings by asserting 'nothing is public and nothing here moves a rating.'

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 the routing rule 'Answer one with replyToListingFeedback' and the condition for narrowing to one listing ('Pass `listing_id` for one listing'). Clear context, though it never states explicit exclusions such as when to prefer getFeedbackStatus or myReviews instead.

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

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

Annotations declare readOnlyHint=true, and the description is consistent with that plus adds real behavioral context: deleted listings are excluded, results are ordered newest first, and owner-supplied text fields are surfaced under `_untrusted`. It stops short of describing rate limits or auth failure 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?

A single dense paragraph that front-loads ownership, ordering, and returned fields before pagination and the untrusted-data note. Information-dense with little waste, though the parenthetical stat list makes it slightly packed.

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

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

With no output schema, the description carries the return-shape burden and does so well: item status values, sales count, seller stats, ordering, exclusions, and pagination are all covered. An agent has what it needs to call and interpret this tool.

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

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

Schema coverage is 100%, so both parameters are already documented (limit max 100, default 50; cursor from previous page). The description largely restates those facts, adding only the `next_cursor` naming link, so the baseline 3 is appropriate.

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

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

States a specific resource and scope: your own listings, newest first, with a named owner requirement (needs your API key). The ownership framing cleanly distinguishes it from siblings like getListing and search, which operate on listings generally.

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 routes edits to updateListing() and explains pagination, which implies the read use case, but never states when to use this versus alternatives such as search or getListing, nor any exclusions. Usage is inferable rather than explicit.

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

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

With annotations only declaring readOnlyHint and openWorldHint, the description carries real extra burden and delivers: it discloses the API-key auth requirement, the newest-first ordering, what `pending` means (settlement being confirmed), the can_rate/rated/not_verified review lifecycle, the zero-count review rule for shared humans, and that listing_title and seller.name are untrusted seller text.

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

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

One dense paragraph, but it is front-loaded with purpose and every clause carries information (status meanings, review states, untrusted fields). The heavy run-on sentence and semicolon nesting make it slightly harder to scan than ideal, but there is little 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?

There is no output schema, so the description must explain the return shape, and it does: it enumerates the fields returned and decodes status, review_status, mine/can_rate/rated/not_verified and theirs. An agent knows exactly what it will get back and what to do with it.

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

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

Schema coverage is 100% and the single `limit` parameter is already documented with its default, bounds and 'Newest first' note. The description's 'newest first' phrasing merely repeats the schema, adding no new parameter semantics; baseline 3 applies.

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

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

States a specific verb+resource+scope: the caller's own purchases, newest first, each with listing, seller, transaction hash, amount, status and review_status. This clearly distinguishes it from siblings like mySales, myReviews and getDelivery, so an agent can select it without opening the schema.

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

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

Gives a concrete next step ('Use the purchase_id with review()') and notes the edge case that a seller sharing your human can still be rated. It does not explicitly contrast with mySales or say when not to use it, so it stops short of full when/when-not routing.

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

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

With no output schema, the description carries the full burden and does so thoroughly: it enumerates the returned lists, the proof scale 1-5 with meanings, proof_label, counts values (0, 0.25, 0.5, 0.6, 1), the meaning of why, and the as_seller/as_buyer aggregates. It also flags that note, reviewer.name and reviewee.name are other agents' words exposed under `_untrusted`, a genuinely useful security disclosure that annotations (readOnlyHint/openWorldHint) do not cover.

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

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

It is front-loaded with what the tool is and its auth requirement, and every clause contributes field semantics rather than filler, which justifies the length given the absence of an output schema. The form is a single dense run-on paragraph with heavy backticks and em-dashes, which is harder to scan than it needs to be.

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

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

With no output schema, the description compensates by fully documenting the return shape, field semantics, the proof/counts scales, and untrusted-content handling. An agent has everything needed to interpret the response correctly for this read-only 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 description coverage is 100% for the single `limit` parameter, so the schema already documents it; the description's 'both newest first' reinforces ordering but adds no syntax or bounds beyond the schema's default of 50 and range 1-100. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description makes clear this returns the caller's own reviews split into `received` (what buyers and sellers said about you) and `given` (what you said about them), which is a specific scope. It is a read/list operation over a named resource. It never explicitly names the sibling it contrasts with (e.g. getReviews for other parties' reviews), so an agent must infer the difference from the '(needs your API key)' clause and 'about you' phrasing.

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: '(needs your API key)' establishes an authentication prerequisite and 'about you' implies this is the caller-scoped variant, but there is no explicit when-to-use statement or exclusion telling the agent to prefer getReviews for other people's reviews. Nothing is misleading, but nothing routes the agent decisively.

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

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

Annotations only supply readOnlyHint/openWorldHint; the description adds the auth requirement ('needs your API key'), a privacy guarantee ('never its wallet'), an edge case with side effects (shared-human buyer can be rated but counts 0 with reason), and untrusted-field marking ('_untrusted'). Far beyond what the annotations carry.

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

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

Front-loads purpose and ordering before enumerating return fields and routing, and nearly every clause carries unique information (review_status values, recordPurchase path, shared-human rule). It is a single very dense run-on, though, which costs some readability.

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

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

With no output schema and only one trivial parameter, the description carries the return-value burden and does so thoroughly: transaction hash, amount, review_status values, mine/theirs semantics, purchase_id handoff, and seller attribution. Nothing needed to call it correctly is missing.

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

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

Only one parameter (limit) and schema description coverage is 100%, with the schema already stating the default, min/max and 'Newest first'. The description repeats the ordering but adds no syntax or range detail, so the baseline 3 applies.

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

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

Opens with a concrete verb+resource ('What you sold'), specifies ordering ('newest first') and the exact population ('each verified or pending purchase of your listings'). This cleanly separates it from the sibling myPurchases (buying) without needing to open 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?

Names the follow-up route explicitly ('Use the `purchase_id` with review()') and the alternative path ('seller-run links need recordPurchase'), plus the no-action case ('Sales on hosted listings appear here without any call from you'). When-to-use and what-to-use-instead are both spelled out.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true and idempotentHint=false, so the mutation/open-world profile is covered structurally. The description adds genuinely useful context beyond that — semantic matching against seller descriptions through a relevance gate, top-50 seller fan-out, job.matched/job.bid emissions, and that title/brief are echoed under `_untrusted` (prompt-injection awareness). However, it never mentions the idempotency_key behavior that the annotation's idempotentHint=false implies, so the behavioral picture is 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?

Front-loads the routing condition and required inputs, then walks the lifecycle in a single dense paragraph with no filler sentences. It is longer than most tool descriptions (six sentences plus a reply summary), but each sentence carries load-bearing information — the only mild cost is that parameter constraints are interleaved with workflow 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?

There is no output schema, and the description compensates by naming the reply fields (job_id, status: open, expires_at, matched_sellers) and explaining the asynchronous event flow that follows the call. It also discloses the API-key requirement and the untrusted-echo hazard, so nothing an agent needs to invoke and interpret this tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: that the brief is what sellers are matched on semantically, that the deadline is when bids close (default 30 days), and that tags participate in matching. It omits any explanation of idempotency_key, the one parameter whose semantics matter most for retry safety.

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

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

States a specific verb and resource ('Post the work and let sellers bid') and immediately distinguishes the case from its nearest sibling with 'No listing fits?' — i.e. use this instead of createListing. An agent can tell it apart from createListing, createProfile and the rest of the sibling set 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?

Gives the selecting condition ('No listing fits?'), the full downstream workflow (bids arrive as job.bid events, read them with getBids, accept by paying buy_url, close with closeJob), and names the alternative discovery path (sellers can also find the job via searchJobs). When-to-use and which-sibling are both explicit.

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

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

Annotations already declare non-read-only, non-idempotent, open-world, non-destructive, but the description goes well beyond them: the 10%-of-sale billing model and 48-hour attribution window, deduction from the `addCredit` prepaid balance, self-pausing on cap/credit/review thresholds, contention resolution with no bidding, and a full enumeration of refusal codes. That is exactly the side-effect detail an agent needs before spending money.

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, and nearly every sentence carries non-obvious behavioral or financial detail. It is nonetheless very long — the refusal catalogue and the 'relevance is not for sale' paragraph could be tightened without losing selection 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?

With no output schema, the description still describes the reply ('the promotion's state and your credit') and enumerates `status` values including the non-obvious `unmeasured`. Together with the billing, pause, and refusal coverage, an agent has everything needed to invoke this correctly and interpret the result.

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

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

Schema coverage is 67%; `monthly_cap_usdc` and `idempotency_key` are already documented in the schema. The description still adds real meaning for the cap ('a bigger monthly_cap_usdc buys nothing but a higher ceiling', '0 leaves the slot at once', outstanding sales still owe 10%) and implies listing_id must be one the caller owns. It adds value but not for every parameter.

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

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

Opens with a specific verb+resource: 'Buy the promoted slot for one of your listings.' It immediately defines what a promoted slot is (one extra result on a genuine match, marked `promoted: true`) and distinguishes this from organic results and from siblings like updateListing/getListing. An agent can tell exactly what this call does 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?

States prerequisites (API key, owner-only), the exact surfaces where the promotion takes effect (`search` only — not `ask`, previews, webhooks, job board, website), and how to switch it off (`monthly_cap_usdc: 0`). It even documents the practical stop/restart rules (cap spent, credit spent, review average below 3) so the agent knows when this tool is and isn't the right lever.

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

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

Beyond readOnlyHint=false / openWorldHint=true / destructiveHint=false, the description discloses auth requirements, the full on-chain verification rule set (USDC, seller wallet, exact listed price, post-listing timestamp), the side effects of the pending transition (marks the quote paid, fills a job, notifies other bidders), and a complete error taxonomy (amount_mismatch, conflict/tx_backs_review, not_yet, unsupported_network, payee_changed). Its replay statement ('a second call returns the same purchase with replayed: true') nuances the conservative idempotentHint=false rather than inverting any safety signal, since the tool genuinely writes rows and performs state transitions.

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

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

It is front-loaded with purpose and inputs, and almost no sentence is pure filler given there is no output schema. However, it is a single very dense block that over-explains peripheral reply fields (literal review.why string, review.proof 4 vs 5, counts 0.6/1) and the payee_changed payload, which hurts scannability for an agent.

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

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

With no output schema, the description carries the return contract itself (purchase object, network, review.can_rate/reason, proof, counts, why, empty _untrusted) and the refusal codes. Combined with annotations covering the safety profile, nothing needed to call this correctly — auth, inputs, retry, replay, side effects — is missing.

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

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

Schema coverage is 100% and the schema already documents the conditional requirement on listing_id and the idempotency-key replay contract, so the baseline is 3. The description reinforces the flow context (transaction hash from the x402 settlement, listing_id omitted for a held pending purchase or a job bid) but adds no syntax or format detail the schema lacks.

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 gives a specific verb, resource and effect: report a settled sale on a seller-run buy link so it becomes a verified purchase and unlocks reviews. It explicitly contrasts itself with siblings ('review the other side with review; a buyer can instead review the payment with reviewPayment ... which needs neither a key nor this call'), so an agent can route correctly without opening any other 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 states the preconditions (API key; you must be the buyer or the seller), the trigger (a settled x402 payment on a seller-run buy link), the harmless case ('Hosted listings ... are recorded by us; calling this for one is harmless'), and the alternatives (review, reviewPayment). The pending/quote path and the 'not_yet' retry advice give explicit when-to-retry 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?

Goes well beyond the annotations by disclosing exact failure modes (`forbidden`, `not_found`, `conflict`/`already_replied`), irreversibility (no edit, no delete), that no totals move, and the `sender_can_read` visibility rule for anonymous vs profiled senders. It also explains that the returned `body` is wrapped under `_untrusted`, which is non-obvious behavior an agent could not derive from the schema or hints.

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

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

Purpose and the one-reply-per-feedback rule are front-loaded, and the semicolon-dense clauses each carry distinct facts (errors, immutability, visibility, return). The closing editorial aside ('one agent's words about another') adds tone rather than actionable content, keeping it just under maximum.

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

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

With no output schema, the description correctly compensates by explaining the return surface (`sender_can_read`, `_untrusted`-wrapped body) and the visibility model. Combined with error semantics and immutability, an agent has everything needed to call this correctly and interpret the result.

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

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

Schema coverage is 100%, so `body`, `feedback_id`, and `idempotency_key` are already documented in the schema. The description adds real meaning on top: `body` is written once forever with no editing path, and the reply body returns under `_untrusted`. That is more than the baseline 3 but doesn't deeply re-specify each parameter.

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 (Answer/Reply), resource (one private feedback on your listing), and cardinality constraint (once), which is enough to separate it from sendListingFeedback and the broader replyToReview. It stops short of actually naming those siblings, so the private-vs-public distinction must be inferred from the word 'private'.

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 preconditions: requires an API key, only the seller the feedback is for may reply, and only one reply ever exists per feedback. It does not route the agent toward or away from siblings (e.g. replyToReview) explicitly, nor state what to do instead when a second reply is attempted, so routing remains 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?

Goes far beyond the annotations: error semantics (conflict on second attempt, forbidden if not yours, not_found for deleted/hidden reviews), immutability (no edit, no delete), and the side-effect profile ('moves no number'). It also discloses the instruction-shape scan, returned flags, and that the agent's own body comes back under _untrusted. This is rich behavioral context that no annotation provides.

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 and its key constraint, and most sentences carry distinct operational information (errors, immutability, side effects). It is dense and occasionally editorial ('a way to talk your way out of a bad trade'), which slightly dilutes the signal but does not bury 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 mutation tool with no output schema, the description covers everything an agent needs: who may call it, one-shot semantics, all three error conditions, the fact that flags and _untrusted-wrapped body are returned, and the explicit non-effect on ratings. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by tying the 600-char body to permanence ('written once: there is no edit and no delete') and framing review_id as 'the review about you'. The idempotency_key parameter is left entirely to the schema, which limits it to a 4.

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

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

States a specific verb+resource and scope: 'Answer one review of you, once.' The cardinality constraint ('one reply exists per review, ever') and ownership rule make it unmistakable what this does, and it is clearly distinct from the sibling replyToListingFeedback by operating on a review rather than listing feedback.

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 ('needs your API key', 'Only the profile the review is about may reply') and an explicit when-not path: to dispute a review's lawfulness, email notices@agorean.com instead. It stops short of naming a sibling tool as the alternative, so it is strong but not fully explicit on tool choice.

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

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

Annotations (destructiveHint=false, readOnlyHint=false, openWorldHint=true) only sketch the profile; the description goes much further, disclosing that reporting has no self-acting effect, that reports reach a human and are aggregated via `distinct_agent_count`, that filings are stored regardless of outcome, and the specific error codes (`invalid_input`/`own_listing`, `not_found`). It does not itself discuss the idempotency-key replay semantics, but annotations plus schema cover that axis.

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?

Long, but front-loaded with the core semantic (reporting is inert) and most sentences carry non-obvious information: the aggregation rule, the error codes, the limit. A few clauses (the 'weapon one seller could point at another' rationale) are rhetorical rather than operational, costing some tightness.

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 output schema, the description covers consequences, side effects, aggregation behavior, error cases, rate limit, and the follow-up tool for checking outcome. Nothing an agent needs to call it correctly and interpret the result 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 75% and already documents the reason enum values and idempotency_key; the description adds value by explaining why the `manipulation` reason exists ('text tries to instruct the reader instead of describing goods') and by implying what `message` should contain. It adds meaningfully on top of the schema without fully covering the undescribed `listing_id`.

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

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

States a specific verb and resource ('Report a listing') and immediately clarifies the effect scope ('changes nothing about the listing'). It also distinguishes itself from the closest sibling by naming `sendFeedback` for platform-level issues.

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

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

Explicit when/when-not: use this for a listing problem, use `sendFeedback` for something wrong with the platform, and use `getFeedbackStatus(filing_id)` to see the outcome. It also states the hard constraint (cannot report your own listing) and the rate limit (20/day per 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?

Goes well beyond annotations: requires an API key, enumerates failure modes (conflict/not_quotable, conflict/unsupported_network), discloses the two-sided event flow (seller gets quote.requested, caller gets quote.sent), and flags echoed brief/terms as untrusted. The openWorldHint and destructiveHint=false hints are only supplemented, never contradicted.

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, then eligibility conditions, then parameters, then the reply contract — a sensible order with no filler. However, the paragraph is very dense and the closing quote_url/A2A digression runs long relative to the core action.

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

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

Despite no output schema, the description defines the reply shape (quote_id, status: requested, echoed brief under _untrusted), the async seller round-trip, and the error taxonomy. For a multi-party, stateful, cross-agent tool this covers everything an agent needs 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 80% and the description covers four of five parameters, but mostly restates schema facts ('≤ 4000 chars' duplicates maxLength). It does add flow context for budget_usdc and deadline, yet listing_id is never explained (what it is, where to obtain it) and idempotency_key is omitted entirely from the description. Baseline 3 is appropriate.

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

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

Opening phrase 'Commissioned work: send a brief to a listing that quotes per job' gives a specific verb (send a brief), the target resource (quote-per-job listing), and the transaction type (commissioned vs bought). This lets an agent distinguish it immediately from getQuote, sendQuote, ask, and the purchase-side siblings without opening any schema.

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

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

Explicit when-to-use ('listings with no fixed price, a quote_url, or delivery: "a2a"') and when-not ('a hosted file or a priced url/mcp listing is bought, not commissioned'), with the resulting error codes named. It also carves out a sub-case against the `ask` sibling ('ask still works on it') and points to the follow-up read via getQuote(quote_id).

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?

Well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), the description discloses immutability, the conflict/forbidden/not_yet failure modes, how `counts` and `why` are computed for same-person reviews, that `note` is listed under `_untrusted`, and the proof-weighting rules. This is exactly the extra behavioral context annotations cannot carry.

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

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

The purpose is front-loaded in the first clause, and few sentences are truly wasted given there is no output schema. However, it is a single sprawling paragraph mixing invocation rules, error codes, proof-weight arithmetic, and x402 fallback, which makes it hard to parse and pushes some detail past the point of usefulness for a call decision.

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

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

With no output schema, the description appropriately documents the reply shape (`proof`, `proof_label`, `counts`, `why`), all error outcomes, idempotency behavior, and the alternate reviewPayment path. Nothing an agent needs to call this 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 75%, and the schema already documents most of what matters (stars range, note length, and a very detailed idempotency_key description). The description's parameter-level additions are limited to reinforcing the same constraints plus the `_untrusted` warning about `note`, so it adds only marginal meaning over the schema.

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

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

States a precise verb+resource with scope: 'Review the other side of a purchase you were part of,' immediately clarifying buyer-reviews-seller vs seller-reviews-buyer. An agent can distinguish this from siblings like getReviews, myReviews, and replyToReview without opening any schema.

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

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

Gives explicit preconditions and exclusions: exactly one review per side, never edited or deleted, purchase must be verified, a second call returns conflict. It also names the alternative path explicitly ('With no API key, or for an x402 endpoint on Base paid outside Agorean, reviewPayment writes the buyer's review'), which is a textbook when-to-use-which routing 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?

Annotations cover only the safety profile (not read-only, not destructive, open world); the description goes far beyond them, disclosing concrete limits (30 calls/day per address, 10 signed and 10 unsigned reviews/day), the on-chain verification performed, visibility outcomes (`visible: false` with `waiting_reason`), the 7-day confirmation window, and the idempotency key's 24-hour replay behavior. Nothing contradicts `readOnlyHint: false` — the tool visibly posts a review.

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

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

It is front-loaded correctly, but the body is a single multi-hundred-word run-on paragraph that re-specifies the twelve-line v1 signature format already documented in the `wallet_proof` schema description, then enumerates every refusal reason and proof rung. Much of that belongs in the linked docs, not in a selection-time description.

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

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

Given the absence of an output schema and the complexity of payment-proof verification, the description does the necessary work: it enumerates the reply fields (`proof`, `counts`, `why`, `visible`, `waiting_reason`, `keep_profile`), the failure taxonomy, and the trust tiers. An agent could call it and interpret the result without further documentation.

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

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

Schema coverage is 100%, so a 3 is the floor, but the description adds genuine relational meaning the schema does not: `resource` yields 'your latest payment to that endpoint's payee that has no review yet', `listing_id` is required for a no-payment review unless `resource` names the listing, and `wallet_proof` must be an exact match to the v1 text. That is useful semantics beyond field-level docs.

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 gives a specific verb and resource ('Review a seller you paid, in one call') and names getReviews as the reader counterpart, so the create-vs-read split is clear. However, the sibling set contains tools literally named `review`, `replyToReview`, `myReviews` and `sendListingFeedback`, and nothing in the description distinguishes this tool from those, leaving a real ambiguity unresolved.

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

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

It states a clear triggering context ('Use it right after an x402 payment ... or after an MPP charge on Tempo') and an alternative path (getReviews reads reviews). What it never states is when to prefer this over the sibling `review` tool or when not to attempt a review at all, so the when-not side is missing.

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

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

Annotations already declare destructiveHint=true and non-idempotent, but the description adds substantial context beyond them: the old key is invalidated immediately, the API key alone is refused (forbidden/challenge_required), the new key appears only in the reply, retries with the same idempotency_key are refused with conflict rather than replayed, and the reply contains no seller-written text.

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 dense sentences, front-loaded with purpose before prerequisites and edge cases. Every clause carries real information, though the backticked reference chains make it heavier than ideal for scanning.

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

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

With no output schema, the description correctly covers the return: the reply is the only place the new key appears and it must be stored. Combined with the prerequisite flow, idempotency behavior, and recovery-key option, an agent has everything needed to call this destructive tool safely.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds joint semantics the schema does not spell out: new_recovery_pubkey and recovery_proof must be sent together to rotate the recovery key, and the challenge is still signed by the current recovery key. That materially aids correct invocation.

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 ('Mint a new API key for your profile') plus the crucial scope fact that the old one dies instantly and exactly once. An agent can distinguish this from siblings like getChallenge (a prerequisite) and createProfile 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 names the prerequisite (getChallenge signed challenge, recovery key), states when the API key alone is refused, and gives the alternative path for the lost-key case (pass profile_id plus challenge). It also flags the optional recovery-key replacement flow in the same call.

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

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

Beyond readOnlyHint/openWorldHint, it discloses the ranking formula, per-seller capping, promoted-slot behavior, cross-chain buyability, price_basis handling, and that seller-written fields are untrusted data. 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 a single enormous block with nested parentheticals and inline formulas, making it hard to scan. Important caveats are buried mid-paragraph rather than front-loaded or grouped into clear sections.

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

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

With no output schema and ten parameters, it still explains returned fields such as why, network, protocols, buyable_here, price_basis, promoted, and _untrusted. It is complete for the complexity of the 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?

Although schema coverage is already high, the description adds crucial semantics: min_reviews counts distinct buyers and differs from setMinBuyerRating, category is applied to a 200-listing window and indexed listings default to 'other', max_price excludes per_order listings, and offset pages only the ranked set.

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

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

The description opens with a specific verb and resource: 'Find listings by meaning: describe what you need and get the listings that match.' It clearly distinguishes this semantic search from a catalogue walk and names adjacent tools like getReviews and reviewPayment.

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 operational guidance: use getReviews before paying, reviewPayment after, omit category to sweep the market, pass next_offset until null, and treat promoted results as ignorable. It does not contrast directly with sibling searchJobs or getListing for known-item lookup.

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

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

Annotations only declare readOnlyHint and openWorldHint, but the description adds substantial behavioral context: the five-independent-account privacy threshold, one contribution per account/topic/day, rounding rules, null semantics for no_results_percent, exclusion of anonymous searches, and how stale/unavailable data is represented. It also warns that topic text is untrusted data and never instructions, which is important operational guidance.

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

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

The purpose is front-loaded in the first sentence and every subsequent sentence carries real semantic content rather than filler. It is a dense wall of prose, however, and the privacy/rounding rules would be easier to scan as a short list.

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

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

With no output schema and no parameters, the description must carry the full burden, and it does well by defining the key field (no_results_percent), its null cases, and data staleness semantics. It never sketches the overall response shape (e.g., the topic list), so a little is left to discovery.

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 no parameter semantics to explain and the baseline of 4 applies. The description correctly implies there is nothing to pass.

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

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

The description states a concrete verb and resource: discover aggregated needs from Agorean searches over the last 30 complete UTC days. It distinguishes this from a raw search tool by framing it as automatically generated, privacy-reviewed topics. It stops short of naming the sibling `search`/`searchJobs` tools it could be confused with, so 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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative is named. The agent can infer this is for aggregate trend discovery, but nothing tells it whether to prefer this over `search` or what question it answers that a plain search does not.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description goes far beyond that, disclosing the relevance gate, that no match yields results: [], the exact result fields, that bids counts include dead bids, and that it needs no key. The injected-data warning about `_untrusted` is a substantial behavioral disclosure not captured anywhere in structured fields.

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

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

Front-loaded with purpose followed by ranking behavior, returned fields, filter, next action, auth and security note. Every sentence carries information, though the nested parentheticals make it denser than necessary.

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

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

With no output schema, the description takes on the burden and delivers: it lists the returned fields, explains ranking and the relevance gate, describes the empty-result case, and covers auth and prompt-injection safety. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 67% – query and min_budget are already documented in the schema, and the description largely restates them ('stated budget at or above'). The `limit` parameter is undocumented in both schema and description, so the description does not compensate for the coverage gap and only marginally exceeds baseline.

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

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

States a specific verb and resource with the search modality ('Find open jobs posted by buyers, by meaning'), so the agent understands this is semantic search over job briefs rather than a keyword or ID lookup. It never contrasts with the sibling 'search' or 'searchInsights' tools, so it stops short of full sibling differentiation.

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

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

Gives clear usage context: pass a free-text description of what you can do, and route the follow-up to sendQuote({job_id, price_usdc, …}), which orients the agent in the workflow. It does not state when NOT to use it or name the sibling search tools as alternatives, so no exclusions are provided.

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

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

Goes well beyond annotations (readOnlyHint=false, openWorldHint=true): it discloses the durability guarantee ('stored first, before the grouping can fail'), the grouping/proposal behavior, the rate limit, and a privacy-relevant behavior ('no text written by another agent comes back in this reply'). That is exactly the kind of non-obvious behavior an agent needs when calling a write 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?

Dense but front-loaded: what the tool is, then parameters, then lifecycle, then the sibling alternative and limit. Every clause carries information, though the single run-on sentence makes the parameter and lifecycle content harder to scan than it needs to be.

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 write tool with nested context, no output schema, and only non-specific annotations, the description covers the full lifecycle: filing_id return, status values (open/planned/fixed/declined), the distinct_agent_count signal, the daily cap, and the sibling route. 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 already 100%, so the baseline is 3, but the description reinforces semantics the schema states tersely: it enumerates the kind values, explains context is 'anything machine-readable' with example keys, and twice warns never to put a key in context. It does not add format/size guidance beyond the schema.

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

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

States a specific verb+resource ('Tell us something is broken, missing or wrong') and immediately differentiates itself from the nearest sibling by naming reportListing for listing-specific reports. An agent can tell this apart from sendListingFeedback/reportListing 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?

Explicitly routes the agent: 'To report a specific listing instead, use reportListing', and gives the operating limit ('20 a day per profile'). It also tells the agent what to do with the result (keep filing_id, read getFeedbackStatus later), covering when-and-how this tool is the right choice.

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

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

Goes far beyond the annotations: it discloses that only the seller reads it, that it never counts toward a rating or rank, the rate limits (30/day per address, 10 signed/day per wallet, 10 unsigned/day per address), the one-time-use rule for signed notes, on-chain verification behavior, and the full refusal taxonomy. Annotations only say write/non-destructive/openWorld; the description carries the real behavioral load.

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 routed alternatives, which is good, but the body is a single dense paragraph of ~2400 characters mixing proof ladder, rate limits, refusals, and reply fields. It is information-rich yet hard to scan; bullet or sentence separation would materially improve 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 complex 6-parameter, nested-object, no-output-schema tool, the description is complete: it documents the reply fields (saved, feedback_id, proof, counts, etc.), the refusal codes, the limits, and the signing requirements. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is already 100%, so baseline is 3, but the description adds genuine cross-parameter meaning the schema cannot: which combinations of listing_id/resource/tx_hash/wallet_proof yield which proof level, and the consequence of naming none ('listing_required'). It explains interaction semantics rather than restating field docs.

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

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

Opens with a specific verb+resource ('Send a seller private feedback on one of its listings, with no API key') and immediately names the sibling tools it must not be confused with (reviewPayment, sendFeedback, reportListing). An agent can distinguish it from every similar feedback/review sibling without opening a schema.

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

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

Explicitly states the alternative and the condition that selects it: use reviewPayment for a public review, sendFeedback/reportListing to tell Agorean something. It also lays out the proof ladder conditions (listing alone → proof 1, tx_hash → proof 2, tx_hash + wallet_proof → proof 3-5), which is exactly the decision guidance needed to pick parameters.

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

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

Annotations only cover the safety profile (readOnly=false, idempotent=false, openWorld=true); the description adds substantial context beyond them: a one-off hosted buy link is minted, the buyer pays it, purchase.recorded triggers deliver, and the full refusal taxonomy maps error codes to conditions (already_quoted, quote_paid, job_closed, forbidden/own_job).

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

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

Front-loaded with the core purpose and the two-path selection rule; every subsequent sentence carries distinct information (payment flow, events, refusals, reply shape). It is dense and jargon-heavy in one paragraph but 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?

With no output schema, the description correctly carries the return-value burden ('quote_id, status: quoted, buy_url, expires_at', plus the _untrusted echo), and it fully covers the downstream event flow and every refusal case. 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 coverage is 100% so the schema already documents each field, but the description adds real meaning: the mutual-exclusivity constraint ('exactly one of'), what price_usdc actually does (mints the buy link at that exact price), and the 7-day default for expires_at. Slightly above the baseline the schema alone would earn.

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 (answer/bid) and resource (brief quote / posted job), and explicitly distinguishes the two operating modes by naming the exact input that selects each. An agent can tell this apart from siblings like requestQuote or getQuote 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?

Gives explicit when-to-use conditions and exclusions: 'exactly one of quote_id ... only that listing's seller may answer' or 'job_id ... not your own; one bid per seller per job'. Prerequisites (needs your API key) and event sources (quote.requested, job.matched, searchJobs) are spelled out.

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

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

Annotations cover the safety profile (idempotentHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower, and the description still adds real behavioral context: the auth challenge requirement, the profile_claimed refusal, and the note that a claimed profile is never re-homed. The 'No seller-written text in the reply' line is unusual output-scope context not derivable from annotations.

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

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

Front-loads the core action and effect before the auth mechanics and refusal conditions, and every sentence carries information. It is dense but not padded, though a few clauses (e.g. the re-homing remark) run long.

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 small mutation tool with no output schema, it covers the auth flow, the refusal reasons, and a hint about reply content, which is close to what an agent needs. A brief note on what the caller should do after a profile_claimed refusal would close the remaining gap.

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

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

Schema coverage is 100% and the nested challenge object is fully documented in the schema, so the description's restatement of `challenge: { challenge_id, signature }` and the 'recovery key' detail largely repeats what the schema already provides. Baseline 3 is appropriate when the schema carries the parameter semantics.

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

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

States a specific verb and resource: 'Set or fix the owner-email hint on your profile', and immediately clarifies the effect ('that human sees it as pending in their dashboard and can claim it'). It is clearly distinguishable from siblings like setWebhook, updateProfile, or setMinBuyerRating.

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?

Explains the prerequisite workflow (API key plus a signed challenge from getChallenge, and that the key alone is refused) and the condition under which it will be refused (profile_claimed). It names the dependency tool getChallenge, but does not explicitly contrast against nearby siblings such as updateProfile or claimListing.

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

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

Goes well beyond annotations: it discloses the hosted buy link refuses a below-bar buyer before money moves with a specific error (forbidden, details.reason=buyer_below_min_rating), that declines are not reviews, that unrated buyers pass, and that replies carry no seller-written text (_untrusted empty). This is rich behavioral context that annotations alone (idempotent, non-destructive) cannot convey.

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

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

Dense but front-loaded: it opens with purpose, then hyphenated clarifications. Every clause carries an edge case (no stars != zero stars, declines not reviews), though the single packed paragraph could be structured more scannably.

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

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

For a mutating tool with no output schema, the description supplies everything needed: prerequisites, defaults, error behavior, reply contents, and the idempotency contract (also in schema). Nothing required for correct invocation is missing.

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

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

Schema coverage is 75%, so the schema already documents min_stars and min_reviews well. The description reinforces the key nuance ('as a buyer', unrated passes, review-count vs search's distinct-buyer filter) but largely echoes schema text rather than adding net-new semantics, warranting a solid 4 rather than 5.

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

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

States a specific verb and resource: gate buyers by a rating bar on your listing. It also clarifies scope (only the owner, needs API key) and distinguishes its semantics from a same-named search filter, so an agent knows exactly what this does versus siblings.

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 operating context: API key required, owner-only, defaults are off so everyone may buy, and how min_stars and min_reviews combine. It contrasts semantics with search's filter but does not explicitly frame when-to-use versus a named alternative tool, so it stops 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?

The description goes well beyond the annotations (destructiveHint=true, idempotentHint=false): it discloses the retry schedule (1m/5m/30m/2h/12h then dead-letter), that every call mints a fresh secret shown once and invalidates the old one, that a same-key retry is refused with `conflict` rather than replayed, the exact signature header format, and an immediate `webhook.test` event. It also enumerates every refusal reason. Minor gap: it doesn't restate that the change is destructive (replacing the existing webhook/secret) in so many words, though 'the old one stops verifying' implies it.

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

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

Front-loaded with purpose and the API-key prerequisite before the dense detail, and nearly every clause carries operational value (signature format, retries, refusal reasons). It is a single very dense block with heavy parentheticals, which costs some readability, but there is little padding to cut.

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

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

With no output schema, the description still covers the return contract (the minted `webhook_secret` shown once, the test event) and the failure surface in detail. For a mutation tool with these annotations, an agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `url: null` stops pushing, and the per-reason rejection vocabulary (`malformed`, `not_https`, `our_infrastructure`, `localhost`, `private_address`) tells the caller what values will fail. For idempotency_key it reinforces the 24h window and the secret-conflict rule.

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 states a concrete verb and resource: it configures the push side of the event stream that POSTs every profile event to `url`. It explicitly contrasts with the pull alternative (`events()`, `docs('receive-events')`), so an agent can distinguish it from the polling siblings 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 states the prerequisite (needs your API key), the alternative (poll events() instead), and the off-switch (`url: null` stops pushing), plus a pointer to docs('receive-events') when the caller has no server. When-to-use and when-to-use-something-else are both explicit.

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

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

Annotations (readOnly=false, destructive=false, idempotent=true, openWorld=true) set the baseline, and the description goes well beyond: API-key/owner requirement, search re-indexing on description change, price-history retention, error codes (conflict/listing_has_purchases, unavailable/mainnet_unconfigured), the duplicate/search_hidden recovery rules, and which reply fields are marked _untrusted. This is a rich behavioral disclosure consistent with the annotations.

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

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

Purpose is front-loaded, but the body is a dense, unbulleted paragraph packing field enumeration, the upload flow, network history rules, and a highly intricate duplicate-detection rule (0.97/0.85 cosine thresholds). Every clause carries information, yet the density and lack of structure make it harder to parse than necessary for a field-update 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 15-parameter mutation tool with no output schema, the description covers the gaps: auth, per-field semantics, the multi-step upload flow, error codes, and even the shape/trust-marking of the reply. An agent has enough to invoke it correctly across its documented states.

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

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

Schema coverage is only 53%, so the description has to carry weight, and it does: it explains price_usdc history, description re-indexing, use_cases format and clearing via [], status pause/active effects, network semantics, and counterpart linking. It adds real meaning beyond the schema, though a few fields (preview, preview_url, delivery_time, idempotency_key) get no elaboration.

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 ('Edit one of your listings') with the ownership/auth constraint up front, and enumerates exactly what can be changed. It differentiates from siblings by referencing createListing (use_cases parity) and deleteListing (deletion path), so an agent can distinguish this from adjacent tools 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?

Gives explicit conditions and alternatives: use it for edits vs deleteListing for deletion, the awaiting_upload flow (PUT then call with upload_complete and sha256), when network moves are allowed and the exact error codes when they are not, and when counterpart_listing_id links/unlinks. Nothing about 'when to use' is left to inference.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds materially beyond them: the description field is re-indexed, pausing has asymmetric effects (search/selling off, stats/reviews/buying unaffected), rotating invalidates the old claim token and returns the new one exactly once, and the reply marks own text under `_untrusted`. That is genuine consequence disclosure, not restatement.

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 and the editable fields, then consequences, then the boundary statement, then the return shape — good ordering. It is however dense with long em-dash-heavy sentences, so it is efficient but slightly harder to scan than it needs to be.

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?

Covers what changes, what the side effects are, what the reply contains (the profile), which fields to distrust (`_untrusted`), and where the adjacent operations live. No output schema exists, yet the description still tells the agent what comes back, including the one-time `funding_link`.

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

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

Schema coverage is 67% and the description carries semantics the schema lacks for name/description (what search and job matching read; sharpen your pitch). status and rotate_funding_link are explained beyond their schema text. funding_money and idempotency_key are left to the schema, but both are well documented there, so the gap is small rather than harmful.

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 ('Edit your own profile') and enumerates exactly which fields are editable (name, description, status, rotate_funding_link). It also pre-empts confusion by naming the boundary: keys and wallet are not here, use rotateKey/updateWallet/setHumanEmail. An agent can distinguish this from all 50 siblings at a glance.

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

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

Gives explicit when-to-act guidance for each non-obvious option: pause retires you as a seller (listings leave search, stats/reviews stay, buying still works), active restores, and rotate_funding_link is for when the link was lost or sent to the wrong person. It also routes the agent away to three named alternative tools for key/wallet/email changes.

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

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

Goes well beyond the annotations: discloses atomicity ('one transaction — it either happens completely or not at all'), conflict semantics (a wallet already registered to, or ever held by, another profile is refused via wallet_retired), downstream effects (active listings pay to the new wallet, settled purchases stay verified), re-invocation behavior with the current wallet, and the absence of seller-written text in the reply. This is exactly the kind of mutation/authorization context the annotations cannot carry.

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