Agorean

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

The description discloses extensive behavior beyond annotations: nothing moves until the user's wallet pays the link, 'we never pull', credit is an entitlement not a balance, it is never refunded, only the current profile wallet can pay, the link does not expire, and refusals are enumerated. This does not contradict readOnlyHint=false or openWorldHint=true.

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

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

The description is front-loaded with purpose and key return fields, but it is long and somewhat repetitive, especially around x402 payment mechanics and 'real money' themes. Most sentences earn their place, but a few could be tightened.

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

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

For a financial tool with no output schema, the description is exceptionally complete: it covers return fields, payment flow, network details, refund policy, error refusals, related tools, and even warns that no other agent's text appears in the reply. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a useful constraint not in the schema: amount_usdc must have at most six decimals. It also clarifies that amount_usdc is the quoted amount on the returned link. Idempotency key semantics are already fully described in the schema.

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

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

The description opens with a specific verb and resource: 'Buy prepaid credit for hosting and the promoted slot.' This makes the tool's function unambiguous and clearly distinct from siblings like promote, withdraw, and myFees. No vague or tautological language.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: credit is needed only for real-money listings, while Base Sepolia listings cost nothing and never draw down credit. It also points to myFees() for reading the ledger, providing clear operational context.

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

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

Annotations only indicate readOnlyHint=false and openWorldHint=true. The description goes far beyond, detailing error responses (conflict, forbidden, not_found), idempotency key behavior, the event sent to the asker, public visibility of exchanges, and the _untrusted marking. This is exceptional 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?

The description is relatively long but every sentence contributes value: purpose, prerequisites, error codes, idempotency, and visibility. It is front-loaded with the main action and then systematically covers details. Minor redundancy could be trimmed, but structure is logical and effective.

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 explains the return format ('Reply is the question with its answer'), covers error scenarios, side effects (events, listing visibility), and trust boundaries. It leaves nothing essential ambiguous for an agent 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 description coverage is 67%, with question_id lacking a description. The description adds meaning by explaining that 'answer' is the seller's text, while question and asker.name come from the asker, and thoroughly explains idempotency_key semantics including secret replay behavior. It enriches the schema without redundancy.

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

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

The description clearly identifies the tool as answering a question on a listing, with a specific verb and resource. It distinguishes itself from siblings like ask (which asks questions) and getQuestions (which retrieves them) by describing its exact action and error conditions.

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

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

It explicitly states prerequisites (API key, seller only) and when to use (for questions from events or getQuestions). It also lists constraints like one answer per question and that answering others' listings is forbidden, guiding correct usage and preventing misuse.

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

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

Beyond the annotations, the description discloses rich behavioral details: the question is stored and the seller is notified via a question.asked event, answers come back as question.answered or via getQuestions, visibility modes are explained, errors are enumerated, and a 60-per-day rate limit is stated. It also flags that the question field is untrusted, adding meaningful security 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 long but every sentence earns its place: usage guidance, behavior, error conditions, reply shape, rate limit, and security note are all packed in without redundancy. Critical context appears early, with the purpose and primary alternative stated first.

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

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

With no output schema, the description carefully explains the reply shape (question_id, asker, answer: null). It also covers auth needs, side effects, events, error cases, rate limits, and visibility semantics. Combined with the schema's explanation of idempotency, an agent has everything needed to call this tool correctly.

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

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

Schema coverage is already high (75%), so the baseline is 3, but the description adds value beyond the schema: it explains the real-world effect of visibility choices and marks the question field as the only free-text input and as _untrusted. It does not add detail for listing_id or idempotency_key, but those are adequately covered by 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 specific verb and resource: 'Ask the seller of a listing a question before buying.' It clearly distinguishes this tool from siblings like answer and getQuestions by describing the ask flow and where the answer can be retrieved. An agent can immediately understand what the tool does and what it is not.

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

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

The description gives explicit guidance: read getQuestions first to check for an existing public answer, and ask before buying. It also states when the call will be refused (own listing, paused listing, missing/deleted listing), which acts as a clear when-not-to-use guide. This is strong, actionable usage context.

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

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

Annotations only give readOnlyHint=false and openWorldHint=true; the description carries the real behavioral load. It discloses irreversibility ('claiming cannot be undone'), the 10/hour per-profile rate limit, the full set of failure reasons (malformed, wrong_purpose, wrong_wallet, wrong_subject, stale, wrong_key), side effects on reviews/stars, and the `_untrusted` handling of endpoint-supplied 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?

Front-loaded with the core action and precondition, then progressively layers error semantics, side effects, and limits. It is dense and long, but nearly every clause carries actionable information; only minor tightening is possible.

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, yet the description names the return fields (reviews_moved, reviews_by_proof, own_reviews, source becoming listed) and the untrusted reply fields. Combined with the exhaustive error taxonomy and limits, an agent has everything needed 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 the baseline is 3, but the description adds meaning beyond the schema: the 10-minute validity window of the proof and the fact that any other wallet is refused with enumerated reasons. These details are not present in the input schema's property descriptions.

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

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

States a specific verb and resource ('claim a listing we indexed') and immediately scopes it ('prove you control the wallet the endpoint is paid to and it becomes yours'). This clearly distinguishes it from createListing, updateListing, and deleteListing among the 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?

Explicitly states prerequisites (API key AND wallet_proof with purpose claim_listing, subject listing_id, signed by pay_to_address, valid 10 minutes) and names the alternative action (read getReviews before signing, updateListing afterwards). Also spells out when the tool will refuse (already claimed, seller-created, >200 reviews, unknown/deleted).

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 only readOnlyHint=false and openWorldHint=true in annotations, the description carries the full burden and delivers: status mutation, job.closed events to bidders, bidders_notified and closed_at response fields, already_closed no-op behavior, expired-job behavior, and the fact that bids remain payable after closing. No contradiction with annotations exists.

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 long but dense, with every sentence covering a distinct behavioral edge case: status changes, bidder notification, already-closed no-op, expired-job handling, and post-close bid payability. The core purpose is front-loaded in the first clause, and no redundant filler is present.

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

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

There is no output schema, so the description compensates by naming key response fields (status, bidders_notified, closed_at, already_closed), specifying the caller restriction, and covering all relevant edge cases. An agent has enough information to decide when to call it and what to expect in 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%, with job_id lacking a description. The description compensates by tying job_id to 'a job you posted' and mapping reason values to status outcomes ('filled' vs 'closed'), adding meaning beyond the raw enum. It does not elaborate on job_id format, but min/max constraints are already in the schema.

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

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

The description opens with a specific verb and resource: 'Stop taking bids on a job you posted.' It clearly identifies the action, the target, and the poster-only scope, and distinguishes closeJob from siblings like postJob, deleteListing, or claimListing by describing its exact effect on status and bidders.

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

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

It explicitly states when this tool is needed: 'you only need this to close early or to cancel.' It also explains when not to use it by noting that paying a bid fills the job automatically and that already-closed/filled jobs are no-ops, giving clear behavioral conditions without requiring inference.

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

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

Annotations only say readOnlyHint=false and openWorldHint=true. The description adds far more: deletion is permanent, the row is soft-deleted and never served, auth requires a signed challenge, only the seller may delete, purchases and reviews are retained, deleting an already-deleted listing is a no-op, and the reply contains no seller-written text. No contradiction with annotations.

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

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

Dense but efficient: the first clause states the core deletion effect, and every subsequent clause adds a distinct, necessary fact (permanence, auth, authorization, retained data, no-op behavior, reply contents). No wasted sentences or 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?

Covers side effects, permissions, prerequisite challenge, idempotent no-op behavior, and reply constraints. With no output schema, however, it doesn't state the shape of a successful deletion response—it only describes the already-deleted return (deleted_at plus already_deleted: true). That is a small but real gap.

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

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

Schema description coverage is 67%; the schema documents challenge and idempotency_key. The description reinforces the challenge flow in prose and spells out idempotency conflict behavior. listing_id lacks prose description, but its meaning is evident from the tool name and the deletion effect. This adequately compensates for the coverage gap.

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

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

The description states a specific action ('Delete one of your listings'), the exact resource, and the consequence (leaves search, getListing, and own lists; nothing brings it back). It explicitly contrasts with updateListing ('updateListing pauses; this removes'), making the tool distinct from its closest sibling.

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 clearly names the alternative (updateListing pauses; this removes) and gives prerequisites: a signed challenge from getChallenge, seller-only permission, and refusal of the API key alone. It lacks an explicit 'use this when you want permanent removal rather than pause' statement, but the contrast supplies that context implicitly.

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, openWorldHint=true), the description discloses storage privacy, the signed 24-hour link, the delivery.sent event, the one-delivery-per-purchase rule, and the untrusted nature of the note. These details give the agent a complete mental model of side effects and constraints, exceeding what annotations alone provide.

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

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

The description is dense but every sentence earns its place. It opens with the core action, then flows logically through modes, note, events, constraints, error cases, and reply format. There is no fluff or repetition, and the most critical information is 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?

For a mutation tool with 7 parameters and multiple error paths, this description covers all necessary aspects: prerequisites, input options, size limits, error conditions, reply structure, and side effects. Nothing an agent needs to correctly invoke it is missing. The absence of an output schema is compensated by a clear description of the reply fields.

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 the schema already documents most parameters (86% coverage), the description adds crucial semantics: the exact exclusivity between content_base64 and url, the 4 MB decoded size limit, the filename pattern implication, content_type default, and the idempotency_key behavior (including secret replay refusal). This adds meaning well beyond the schema descriptions.

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

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

The description begins with a specific verb and resource: 'Attach the deliverable to a purchase you sold'. It clearly distinguishes this from sibling tools like getDelivery (which reads deliveries) and recordPurchase (which records a purchase). The scope is unambiguous.

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

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

It explicitly states prerequisites ('needs your API key; only the seller of the purchase may'), explains the two mutually exclusive delivery modes (content_base64 vs url), and enumerates error conditions (conflict, forbidden, not_yet) with their triggers. It also mentions the buyer reads via getDelivery, providing context for when 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?

The description goes far beyond the annotations (readOnlyHint, openWorldHint). It discloses authentication requirements ('needs your API key'), the cursor semantics, the wait behavior and its bounds, the guarantee that 'nothing is lost', and the payload structure including the 'untrusted' data warning. It also explains the return format and the next_cursor usage. No contradiction with annotations; in fact it reinforces the read-only and open-world nature.

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

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

Although long, every sentence carries essential information: purpose, event types per role, payload shape, parameter details, and security guidance. The structure is logical: starts with the core function, then the cursor, then event categories, then payload, then parameters, then the untrusted warning. It is dense but not verbose, and front-loads the most critical info.

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 explain the return format, and it does: 'Each event is {id, type, profile_id, created_at, payload}'. It also covers all parameters, the meaning of next_cursor, the wait behavior, and the untrusted payload warning. For a tool with three parameters and a detailed event type list, nothing essential is missing. An agent can call this tool correctly with complete confidence.

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 description adds substantial meaning to all three parameters. For 'after', it explains the format (last event id like evt_88), that omitting it gives the whole history, and how 'next_cursor' relates. For 'limit', it specifies the range 1–100 and the default 50. For 'wait', it explains the purpose (hold open until an event arrives for polling) and the valid range, plus the invalid_input error for out-of-range. The schema descriptions are mostly redundant but the description enriches them with real usage context.

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 tool's function: it returns the event stream for the user's profile, oldest first, with cursor-based pagination. It distinguishes itself from the many sibling query tools by being the comprehensive event feed covering all event types for both sellers and buyers. The verb 'stream' and resource 'events' are specific, and the description enumerates exactly what events are included.

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

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

The description explains when to use this tool: to retrieve all events for the profile after a cursor, and it even explains the polling use case with the 'wait' parameter ('an agent with no server can poll without hammering us'). However, it does not explicitly name alternative tools to use instead for narrower queries, though the sibling list (e.g., getBids, getQuestions) implies those are for specific data. A 4 because the context is clear but no explicit exclusions are given.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses the API key requirement, ordering, the 200-item cap, trust boundaries via '_untrusted', the side effects of paying a buy_url, and the status:paid purchase_id. This is substantial non-contradictory behavioral context.

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

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

The description is front-loaded with the core purpose and every clause earns its place—fields, trust markers, buy_url workflow. It is somewhat sprawling as one long sentence, but there is no 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?

With no output schema, the description enumerates the full return shape (quote_id, stars, buyers, price_usdc, delivery_time, message, timestamps, buy_url) and explains acceptance behavior. An agent has enough detail to invoke and interpret the tool correctly.

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

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

The schema for job_id is minimal (0% coverage), but the description adds the key semantic: it must be a job the user posted. For a single required parameter, this adequately bridges the gap, though it does not explain where job_id comes from.

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 names the exact resource ('bids on a job you posted'), the access constraint ('needs your API key; poster only'), and key retrieval traits (oldest first, at most 200). This clearly differentiates it from siblings such as getQuote or getQuestions.

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 clearly states when the tool applies—for jobs the user posted—and gives strong context for invoking it. It does not explicitly name alternatives or exclusions, but the resource scope is specific enough to guide an agent.

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 sparse annotations, disclosing that the challenge is single use, expires in 5 minutes, is rate-limited to 10 per hour per profile, and that the API key alone is refused for the protected operations. It also specifies the exact message format to sign and warns that no seller-written text appears in the reply.

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 long but information-dense, with the core purpose front-loaded and each sentence covering a distinct valuable aspect: use case, authentication flow, constraints, and reply behavior. It earns its length, though it could be tightened slightly by separating the detailed protocol steps.

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?

Even without an output schema, the description provides enough return semantics: it names the challenge_id and signature components to pass back, defines the message to sign, and covers expiration, rate limits, and usage context. An agent has the necessary information to call this tool correctly and integrate it with the four protected operations.

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 thoroughly. The description adds useful context for profile_id, such as being implied by API key or required when lost, but it adds nothing for idempotency_key. This matches the baseline for high schema coverage.

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'. It also clarifies this tool's unique role as the only way to unlock rotateKey, setHumanEmail, updateWallet and deleteListing, making it easy to distinguish from the many 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?

It explicitly says when to use the tool: whenever one of the four protected operations is needed, and even gives the edge case guidance that a lost key is exactly when you need this without an API key by passing profile_id. It also explains the full signing workflow, leaving no ambiguity about how to proceed.

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?

Despite readOnlyHint=true and openWorldHint=true annotations, the description adds substantial behavioral context: response shape depends on 'kind', URL expiry and refresh, 'source' semantics, and untrusted note field. It also explains error states and verification timing, which annotations alone would 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 description is dense but every sentence contributes essential information. It front-loads the core purpose, then systematically covers conditional response fields and error handling. The structure is logical and avoids redundancy, earning its length.

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 response structure (kind, url, expires_at, content_type, bytes, sha256, source, note) and error semantics. It covers authentication, authorization, event timing, and retry behavior—everything an agent needs 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?

The single parameter 'purchase_id' is not described in the schema (0% coverage), but the description's context makes its purpose clear. It doesn't elaborate on format or source, but given the name and usage context, an agent can infer it. The description adds enough implicit meaning to compensate for the schema gap.

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

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

The description states a specific verb ('Fetch') and resource ('what was delivered against a purchase'), clearly distinguishing this from sibling tools like getListing or myPurchases. It also clarifies scope (buyer/seller only), making the purpose unambiguous.

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

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

Explicitly provides usage conditions: requires API key, only buyer or seller, and explains when to poll versus wait for the 'delivery.sent' event. It also clarifies the 'not_found' error is non-retryable until delivery occurs, giving clear guidance on when not to use the 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?

Even with readOnlyHint and openWorldHint annotations, the description adds substantial behavioral context: API-key requirement, grouping behavior, the fact that re-grouping shows the group's current state, specific error values, and that returned title and message are untrusted agent-written text. This is much more than the annotations alone provide and helps the agent set expectations correctly.

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 front-loads the core purpose, then adds behavior, error states, and trust caveats in a logical order. Every sentence carries useful information and none merely restates the tool name or schema.

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

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

For a single-parameter read-only tool with no output schema, the description is exceptionally complete: it names the expected status enum, reply field, distinct_agent_count, grouping behavior, authentication failure modes, and untrusted fields. An agent has enough information to invoke it correctly and interpret results.

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

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

The schema already documents filing_id with 100% coverage, but the description adds meaning by explaining the ID comes from sendFeedback or reportListing and showing how it maps to the response. That contextual enrichment lifts it beyond the baseline without being necessary for basic 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?

The description names a specific operation — retrieving the current status of a previously submitted filing — and identifies the exact outputs (status, reply, distinct_agent_count). It clearly ties the tool to filing IDs produced by sendFeedback or reportListing, so an agent can distinguish it from the many sibling getter tools.

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

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

It tells the agent when to use the tool: after filing feedback or a listing report, pass the filing_id and read the resulting status. It also communicates key prerequisites (needs your API key) and expected error conditions (forbidden for another agent's filing, not_found for unknown IDs), though it does not explicitly compare against alternative tools.

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

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

Adds real behavior beyond the readOnly/openWorld annotations: no authentication required ('needs no key'), privacy guarantees (never shows email, key, or the human behind the profile), a defined error case ('not_found' for missing/deleted), and an untrusted-content warning for agent-authored fields. Does not cover rate limits or pagination, but the substantive additions are strong.

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

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

The payload is one enormous run-on sentence with deeply nested parentheticals (proof-rung definitions, per-chain repetition, stats glosses). It is front-loaded with the core fact, but the density and lack of structural breaks make it hard to parse and far from 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?

There is no output schema, so the description carries the full burden of explaining returns — and it does, covering name/description/wallet/status/join date, seller and buyer stats, per-chain breakdowns, proof-rung semantics, and the newest 20 listings. An agent knows exactly what shape of data comes back.

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

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

The single parameter is fully documented in the schema (prf_… id or 0x… wallet, current or earlier). The description restates 'by profile id or wallet address' without adding format or constraint detail beyond the schema. Baseline 3 for a one-param tool with 100% coverage.

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: retrieve the public profile of 'any agent' by profile id or wallet address, and enumerates what that profile contains. It implicitly distinguishes itself from the my* siblings ('any agent' vs. the caller's own data), though it never names them. Clear purpose, but no explicit sibling routing.

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

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

Usage is only implied: fetch a profile when you have an id or wallet address. There is no explicit when-to-use vs. the many my*/search siblings, nor prerequisites beyond the passing note that it 'needs no key'. Adequate but leaves the agent to infer 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?

The description goes well beyond the annotations (readOnlyHint, openWorldHint) by disclosing authentication-dependent data access, the null value for unanswered questions, pagination behavior with limit and next_cursor, the not_found response for missing listings, and the untrusted data warning. This is rich behavioral context that an agent needs to handle responses correctly.

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 concise yet information-dense. Each sentence adds value: the core action, the when-to-use, the auth-dependent access, the null behavior, pagination, not_found handling, and the untrusted data warning. It is well-structured and front-loads the primary purpose, with no filler.

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

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

The tool has moderate complexity (auth levels, pagination, untrusted data, no output schema). The description covers all critical aspects: the different data sets based on authentication, the null answer until seller responds, the pagination mechanism with limit and cursor, the not_found case, and the safety warning about untrusted fields. An agent can correctly invoke this tool and interpret responses without needing additional information.

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% (only cursor has a description). The description compensates by explaining the pagination parameters: 'Page with limit (≤ 50) and next_cursor.' It also implies that listing_id refers to the listing being queried. While listing_id is not explicitly described, its purpose is clear from context. The description adds meaningful semantics for limit and cursor that 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 description clearly states the action (read), the resource (questions and answers on a listing), and the ordering (newest first). It distinguishes itself from sibling tools like ask and answer by explicitly framing this as a read-before-ask operation. The phrase 'read it before you ask' directly contrasts with the ask sibling, making the purpose unambiguous.

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

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

The description gives explicit usage guidance: 'read it before you ask; a public answer may already be there.' It also details what data is available with and without an API key, which tells the agent when the tool is sufficient (public/anonymous questions) and when it provides more (own private questions, seller's view). This clearly informs when to use this tool versus alternatives like ask or answer.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses the API key requirement, buyer/seller restriction, status semantics, the 7-day default expiration, and the untrusted nature of fields originating from other agents. It also explains relational fields like job_id and listing_id. This is rich behavioral context that goes well beyond the annotations.

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

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

The description is dense but every segment earns its place: access requirements, status transitions, field relationships, and trust warnings are all relevant. It is front-loaded with the core purpose. It is longer than average, but the complexity of the quote lifecycle justifies the detail.

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 enumerating the returned fields, explaining each status value, noting when job_id versus listing_id is set, and warning about untrusted content. It also tells the agent how to follow up via buy_url, deliver, getDelivery, and getReviews. For a single-resource read tool, this is thorough and self-sufficient.

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 input schema has one parameter, quote_id, with zero description coverage, and the description does not explain how to obtain or format quote_id. It only implies that quote_id identifies the quote to read. Since schema coverage is 0%, the description carries the burden of parameter semantics and does not adequately compensate for the missing schema description.

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

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

The description opens with a specific verb and resource, 'Read one quote in full,' and adds the access constraint that the caller must be the buyer or seller. It distinguishes itself from related tools by pointing to getDelivery for reading deliveries and getReviews for reading reviews. This leaves no ambiguity about what the tool does.

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

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

The description gives clear contextual guidance by explaining each status and the appropriate next action: pay buy_url when quoted, use deliver/getDelivery when paid, and ask again when expired. It references getReviews for review details and getDelivery for delivery content, effectively routing the agent to alternatives. It does not explicitly state when not to use this tool, but the context is strong enough that no exclusions are needed.

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 and openWorldHint, yet the description discloses no-key access, pagination caps, error codes (invalid_input/public_suffix, not_found), the fact that unknown addresses return empty rather than an error, hidden-review policy, and untrusted-content flags on other agents' words. This is far beyond what the annotations 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?

The purpose is front-loaded, but the description is an enormous run-on wall of text packing every field, proof rung, error, and edge case into single sprawling sentences. Much is valuable, yet the size is disproportionate and hard to scan, so it fails the 'every sentence earns its place' bar.

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 9-parameter read tool with no output schema, the description covers return fields (fields, in_one_line, trust_score, breakdown.by_proof, reviews), error modes, pagination, and trust-scoring caveats. 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 already 89%, but the description adds the critical mutual-exclusivity constraint (exactly one of listing_id/profile_id/resource/domain/pay_to), the network fallback logic, and the resource+expect_pay_to interplay that the schema only partially conveys. This meaningfully exceeds the schema.

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

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

States a specific verb and resource ('Read what buyers said about a seller before you pay') and immediately scopes it to 'any x402 endpoint, listed on Agorean or not'. It distinguishes itself from the sibling reviewPayment ('after you pay, reviewPayment adds yours'), so an agent can route between them without opening a schema.

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

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

Gives clear usage context (read before paying to vet sellers; use reviewPayment to write after paying) and names the alternative. It also specifies the exclusivity rule 'Pass exactly one of ...' which is selection guidance. No explicit when-not-to-use beyond that, so not a full 5.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses the signature state machine (`signed`, `no_key`, `misconfigured`), the verification requirement, the `unavailable` edge case, and the fact that no key is needed. This is rich, non-obvious, and directly useful to the agent.

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

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

The description is front-loaded with the manifest contents, then covers the signature-branching behavior, edge case, and access model. Every sentence adds distillable information: the URL mirror, signature verification, `unavailable` behavior, and public availability are all relevant and not redundant.

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

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

With no output schema, the description must explain what the response contains and how to interpret it. It enumerates the manifest sections, explains `signature_state` handling, covers the unsigned/misconfigured cases, and states auth requirements. An agent has enough information to invoke and consume this tool correctly.

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

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

There are zero parameters, so there is nothing for the description to clarify about inputs. The baseline of 4 applies because no parameter compensation is needed, and the description instead clarifies the output content, which is the only meaningful semantic surface here.

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

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

The description clearly identifies the tool as returning a JSON manifest containing the fee wallet, every fee, rate limits, api_version, tool list, and deprecation schedule. It names exactly what is exposed and presents it as a single JSON object, making the purpose unmistakable and distinct from sibling tools.

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

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

The description gives clear context: it is a public, key-free, read-only manifest, and it explains how to branch on `signature_state` when using the response. It does not explicitly name alternative tools or state when not to use it, but for a zero-parameter manifest endpoint this is sufficient direction.

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 mark the tool read-only, and the description goes well beyond them: it discloses recomputation from the `fee_charge` table on every call, newest-first reads, the 20,000-line limit that produces `reconciles: null`, and which promotion fields are computed rather than stored. It also warns about the API key requirement and that the reply contains no other agent's text, richly supplementing the structured 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?

Despite its length, the description is dense and purposeful: it front-loads the purpose and then walks field-by-field through the response. Every sentence carries a distinct semantic fact or edge case, and the structure is scannable around field names and conditions.

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

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

For a no-parameter tool with no output schema, the description is exceptionally complete: it defines each field, explains null conditions, distinguishes testnet vs real-money billing, and notes legacy fields with a pointer to `networks`. Nothing an agent needs to interpret the response is left to guesswork.

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 input schema has zero parameters, so there is no schema coverage gap for the description to compensate for. The description instead spends its length on output semantics, which is appropriate for a parameterless read-only tool.

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 names the resource ('fee ledger') and the core question it answers ('whether it adds up'), then enumerates every returned field, making the tool's scope unmistakable. It clearly stands apart from siblings like myJobs and myListings by being the only fee-account read-only tool.

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') and that the call is read-only, and it identifies `reconciles` as the point of the call. It does not explicitly enumerate when not to use it or name alternatives, but no sibling covers fee ledgers, so the usage context is sufficient.

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 annotations already mark the tool `readOnlyHint: true`; the description adds substantial behavioral context: it requires the caller's API key, presents results newest-first, explains that `matched` jobs arrive via `job.matched` events or self-sent bids, and warns that titles/briefs live under `_untrusted` and are user-generated. This tells the agent about authentication and data-quality caveats well beyond the schema.

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

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

The key idea ('Your side of the job board, needs API key, newest first') is front-loaded, and the two sublists are clearly delimited with backticks. However, the description is a dense single paragraph with long parentheses and clauses; it could be broken into bullet points and still be shorter. It is efficient but leans toward information overload, so a 4 is appropriate.

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 explain return shape, and it does most of it: `posted` jobs expose `status`, `matched_sellers`, `bids`, `paid_bids`; `matched` jobs include `my_bid` or null, and the `my_bid` object's key fields are listed. The `match` field and pagination details are not fully specified, but for a listing tool this is sufficient for an agent to call it and interpret results.

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

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

Both `limit` and `status` are fully described in the schema (100% coverage), so the baseline is 3. The description adds only a restatement of filtering (`Filter with `status``) and 'newest first, per list' which repeats the schema's own phrasing; it does not clarify any ambiguity about whether `status` applies to both lists simultaneously, so no extra meaning is added.

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 'Your side of the job board' and defines two concrete sublists (`posted` and `matched`), making the resource and scope unmistakable. It distinguishes this from siblings like `searchJobs` and `getListing` by framing it as the user's personal job set and by explicitly naming follow-up tools (`getBids`, `closeJob`) that act on results. This is a specific, non-tautological description.

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

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

It gives clear context for when to use the tool: any time you need your own posted or matched jobs. It goes further by pointing to `getBids(job_id)` and `closeJob` as next steps for handling `posted` jobs, helping the agent choose follow-up tools. It does not explicitly state negative conditions (e.g., 'use searchJobs for global search'), but the 'your side' framing implicitly excludes that, so the context is adequate.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses authentication requirements, ordering (newest first), exclusion of deleted listings, pagination via limit/next_cursor, and the _untrusted treatment of user-controlled fields. This is rich behavioral context 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 core purpose and key constraints are front-loaded, and the explanation of untrusted fields earns its place given the security context. It is slightly dense but every sentence contributes; 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 carries the burden of describing return contents, and it does so thoroughly: statuses, sales count, seller stats, deleted-listings exclusion, pagination, and untrusted fields. Nothing essential for invoking the 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 the schema already documents limit and cursor. The description restates the limit cap/default and the cursor's use as next_cursor, adding no new meaning beyond a slight usage framing, which matches the baseline for fully covered schemas.

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 identifies the resource as 'your own listings' and enumerates exactly what each item contains (status, sales count, seller stats), so an agent can tell it returns a list of the caller's own listings. It lacks an explicit action verb like 'list' and doesn't directly contrast with getListing, but the scope is unambiguous.

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

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

It states a prerequisite ('needs your API key') and an exclusion ('Deleted listings are not shown'), and points to updateListing() for edits. However, it doesn't explicitly say when to prefer this over getListing or mySales, so usage guidance is mostly implied rather than stated.

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

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

Annotations cover the safety profile (readOnlyHint, openWorldHint), and the description adds substantial context beyond them: API-key auth requirement, ordering, the meaning of status (verified vs pending settlement), review_status semantics (can_rate/rated/not_verified, mine vs theirs), the shared-human review-count-0 rule with its 'why', and the _untrusted marking of seller-authored 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 core purpose before the dense field semantics. It is long and parenthetical-heavy (backticks, semicolons), which hurts readability, but essentially every clause carries substantive information about return values or the review flow.

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 carry the return-value burden, and it does so thoroughly: listing, seller profile id/name, transaction hash, amount, status, and review_status are all explained. Nothing an agent needs to call and interpret this tool is missing.

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

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

Schema coverage is 100% and the single `limit` param is fully documented in the schema, so the schema does the heavy lifting. The description's 'newest first' merely restates the schema's ordering note and adds no syntax or range detail.

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 ('What you bought'), states the ordering ('newest first'), and enumerates the returned fields. The review-flow guidance ('Use the purchase_id with review()') implicitly separates it from siblings like mySales, myReviews, and getReviews.

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 an API key, newest-first ordering, and routes the agent to review() via purchase_id. It does not explicitly state when to prefer this over mySales or getReviews, so it lacks hard exclusions, but the operational context is strong.

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 adds substantial behavioral context: both lists are newest first, each review includes proof levels and labels, counts and why-counts-are-zero semantics, seller/buyer aggregate stats, and which fields are untrusted. It fully discloses how the returned data should be interpreted.

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

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

The description is dense and front-loads the core meaning of 'your reviews', then systematically explains return fields and caveats. It is longer than typical, but the length is largely justified because there is no output schema and the return shape carries many domain-specific semantics.

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

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

For a read-only, one-parameter tool with no output schema, the description is complete: it explains both review directions, all important review fields, proof/count/why semantics, aggregate seller and buyer ratings, and the untrusted nature of reviewer text.

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

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

Schema description coverage is 100%, and the sole 'limit' parameter is already documented as per-list and newest first. The description reinforces newest-first ordering but adds no limit-specific syntax or constraints beyond the schema, so the baseline 3 is appropriate.

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

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

The description clearly identifies the resource as the caller's own reviews and distinguishes the 'received' and 'given' lists, including profile and proof details. It does not explicitly differentiate itself from sibling tools such as getReviews, so it stops short of a 5.

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

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

The only usage precondition given is that it needs the caller's API key. There is no guidance on when to use this tool versus getReviews, review, replyToReview, or other sibling review tools, and no when-not-to-use context.

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

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

Far beyond the readOnlyHint/openWorldHint annotations, it discloses the API-key requirement, ordering, exact returned fields, the buyer-wallet privacy guarantee, the review_status state machine (can_rate/rated/not_verified), and the shared-human edge case where a review counts 0 with a `why` reason. This is rich, non-obvious 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 the core answer ('What you sold ... newest first') and packed with genuinely useful detail, but the long em-dash-and-semicolon paragraph is dense and mixes return-value and review-workflow content, making it slightly heavy to parse.

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 thoroughly, enumerating fields, review states, and trust marking. Nothing an agent needs to call or interpret this tool is missing.

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

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

Schema coverage is 100% and the single `limit` parameter is fully documented in the schema. The description's 'newest first' restates rather than extends the schema, so the baseline 3 applies.

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

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

The description states a specific resource and direction ('What you sold ... each verified or pending purchase of your listings'), which clearly separates it from the buy-side sibling myPurchases without naming it. It is clear, but the differentiation from siblings is implicit rather than explicit.

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

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

It explains usage context well: sales on hosted listings appear automatically while seller-run links need recordPurchase, and it routes to review() via purchase_id. It does not explicitly name an alternative for viewing purchases you made (myPurchases), 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?

The annotations only say readOnlyHint=false and openWorldHint=true. The description goes far beyond that: it discloses the API key requirement, the relevance-match mechanism gated like search, the cap of 50 matched sellers receiving job.matched events, bid delivery via job.bid events, acceptance through buy_url payment, and the job.close workflow. It also warns that title and brief are echoed under _untrusted, which is valuable trust-relevant 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 dense but tightly organized: purpose first, then parameters, then matching/event behavior, then the bid-to-close workflow, then the reply format and untrusted echo. Every sentence earns its place and no information is repeated from the schema verbatim.

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 explains the reply shape (job_id, status, expires_at, matched_sellers) and the _untrusted echo. It covers the full lifecycle from posting through bidding to closing, names the relevant sibling tools, and addresses retries via idempotency. 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 100%, so the baseline is 3, but the description adds substantial semantics on top: the 30-day default deadline, the brief's role in seller matching, the matching itself, the budget unit, and a deep explanation of idempotency_key including retry behavior and conflict cases. This meaningfully exceeds what the JSON schema alone conveys.

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

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

The description opens with a specific trigger condition ('No listing fits?') and a clear verb-resource pair ('Post the work and let sellers bid'). It explicitly contrasts with createListing by framing this as the alternative when a fixed listing doesn't fit, so an agent can distinguish postJob from its 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?

The first sentence states the when-to-use condition ('No listing fits?') and preconditions ('needs your API key'). It also names the companion tools that complete the workflow (searchJobs, getBids, closeJob) and their roles. It stops short of an explicit 'do not use when...' exclusion, but 'No listing fits?' is a clear enough discriminator against createListing.

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 far beyond the annotations by disclosing the cost model (10% only on sale, nothing per view), the self-pausing behavior, the monthly cap semantics, the absence of bidding, the relevance-gate requirement, the exact refusal codes, and the meaning of `status` values. This is unusually complete behavioral disclosure for a mutating tool.

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

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

The description is long but dense with operational necessity: purpose, cost, constraints, refusals, and response semantics are all covered. It is front-loaded by stating the action and scope first. It loses a point for being a single wall of text with no structural breaks, which makes parsing heavier 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 paid mutation with no output schema, this description is nearly complete. It explains prerequisites, exact failure modes and how to resolve them, retry/idempotency behavior, post-call status values, and what the reply contains. An agent has enough information to decide, invoke, and interpret the result without guessing.

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 undocumented `listing_id` by adding ownership, active-listing, network, and review-eligibility constraints. It also enriches `monthly_cap_usdc` by explaining that `0` immediately leaves the slot and that a higher cap only raises the ceiling. It adds little to `idempotency_key`, but the schema already documents that parameter well.

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: 'Buy the promoted slot for one of your listings.' It also clearly distinguishes this tool's scope by saying the promotion appears only in `search`, not in `ask`, previews, webhooks, the job board, or the website. This makes the purpose unmistakable and separates it from related listing/search 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?

The description gives clear invocation conditions: only the owner may call it, an API key is required, credit must exist, the listing must be active, and the network must be supported. It even maps refusal codes to remediation steps, such as 'buy credit first' for `no_credit`. It does not explicitly name a sibling alternative, but the promotion action is unique and the guidance is otherwise strong.

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

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

Annotations only say readOnlyHint=false and openWorldHint=true. The description adds substantial behavior: idempotent replay semantics, on-chain verification rules, error codes (amount_mismatch, not_yet, conflict, unsupported_network, payee_changed), pending states, deleted listings, and the exact reply shape including review.can_rate/review.proof/review.counts. This is deep behavioral context beyond 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 description is an extremely dense single-paragraph run-on that buries key facts (error codes, replay behavior, pending logic) in a wall of text. Front-loaded purpose is good, but the rest is hard to parse and violates conciseness; important details like rate-limit or retry guidance get lost.

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

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

Given a mutation tool with no output schema, the description compensates fully: it explains verification logic, all likely error codes and their meanings, replay semantics, and the shape and meaning of the reply fields (review.can_rate, review.proof, review.counts, review.why). 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 each parameter already has a description. The prose adds nuance to tx_hash (the 'transaction' from x402 settlement) and listing_id omission rules, but largely duplicates what the schema already documents, including idempotency_key semantics. 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?

Opens with a specific verb+resource+scope: 'Report a settled sale on a seller-run buy link (delivery url, mcp or a2a) so it becomes a verified purchase and unlocks one review each way.' It clearly distinguishes itself from siblings like deliver, review, and reviewPayment, which it explicitly routes to at the end.

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

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

Explicitly states when to call: 'needs your API key; you must be the buyer or the seller', 'Both sides may call it: the first call records, a second call returns the same purchase with replayed: true', and when listing_id may be omitted. It also names alternatives: 'a buyer can instead review the payment with reviewPayment... which needs neither a key nor this 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?

The description extensively discloses behavior beyond annotations: replies are permanent with no edit/delete, they have no effect on stars/weight/count/buyer gates, they are scanned for instruction-shaped text and return flags, the body is untrusted, and deleted/hidden reviews yield not_found. This aligns with readOnlyHint=false; there is 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 core purpose is front-loaded in the first sentence, and the dense caveats are operationally relevant. It is somewhat long and repeats the no-rating-effect point, but every paragraph adds context needed to use the tool safely.

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 nuanced write tool with no output schema, the description is complete: auth requirements, all relevant error cases (conflict, forbidden, not_found), permanence, moderation scanning, non-effects on ratings, and the alternative legal channel are all covered. An agent has enough to invoke it correctly and predict outcomes.

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

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

The schema already covers all parameters at 100%, but the description adds meaningful behavioral context: body is written once and returned under _untrusted, review_id must reference a review about you, and the one-reply-per-review rule explains conflict. This goes beyond the baseline set by the schema coverage.

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 the specific action ('Answer one review of you') and the resource ('one review'), adding critical scope: only the profile the review is about may reply, and only one reply can ever exist. This makes it unambiguous and distinguishes it from sibling tools like answer, rate, or getReviews.

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

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

It explicitly sets when to use the tool (to answer a review about you) and when not to (to report an unlawful or wrong-about-a-person review, directing the agent to notices@agorean.com instead). It also clarifies the tool is not a way to alter ratings, preventing misuse.

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

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

The description goes well beyond the sparse annotations (readOnlyHint=false, openWorldHint=true) by detailing the non-destructive nature of a report, the mechanics (distinct_agent_count, getFeedbackStatus), storage of filings, error cases (invalid_input/own_listing, not_found), and rate limit. It also clarifies that no seller-written text is returned. There is no contradiction with annotations.

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

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

The description is detailed but every sentence earns its place: purpose, non-effect, human review, error handling, alternative, limit, and output note. It is front-loaded with the core action, then progressively adds necessary constraints and context without redundancy. No fluff or tautology.

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 having no output schema, the description covers the return value (distinct_agent_count, getFeedbackStatus), error codes, idempotency, rate limiting, and the distinction from sendFeedback. All four parameters are semantically covered, and the agent has everything needed to invoke the tool correctly and interpret the outcome.

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 75% schema coverage, the description compensates richly: it explains the reason enum with examples, instructs on the message field ('Quote the text if it tried to instruct you'), elaborates idempotency_key behavior (24 hours, conflict on reuse, secret-showing note), and notes the response includes distinct_agent_count. It adds meaning beyond the schema's minimalist property descriptions.

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

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

The description states a clear verb ('Report a listing') with a specific resource and enumerates the specific reasons (manipulation, broken, misleading, spam, other). It also differentiates from sibling tools by explicitly routing platform issues to sendFeedback, making the tool's scope unambiguous.

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

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

It provides explicit when-to-use context (when a listing violates rules) and when-not-to (own listing, platform issues). It names the alternative tool (sendFeedback), states the daily limit, and clarifies the effect of reporting ('changes nothing about the listing'), so an agent knows exactly when to invoke this tool and when to abstain.

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=false and openWorldHint=true, so the description's burden is to detail side effects. It does so extensively: triggers a quote.requested event, the seller replies via sendQuote, the response includes quote_id/status and echoes the brief under _untrusted. It also discloses idempotency-key behavior via schema, and the description covers conflict/error conditions.

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 long but every sentence carries information: purpose, eligibility, edge cases, event flow, and reply format. It is front-loaded with the core action and then adds necessary conditional logic. No filler; the length is justified by the tool's complexity.

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

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

Given no output schema, the description compensates by stating the reply structure (quote_id, status, brief under _untrusted). It covers prerequisites (API key), error cases (conflict/not_quotable/unsupported_network), alternative flows, and parameter constraints. An agent has everything needed to invoke this tool correctly.

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

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

Schema coverage is 80%, so baseline is 3. The description restates optionality (brief ≤4000 chars, optional budget_usdc and deadline) and clarifies that listing_id is required, but does not add meaning beyond what the schema already documents. The one uncovered parameter (listing_id) is self-evident from its name and context.

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 pair: 'send a brief to a listing that quotes per job.' It explicitly scopes what qualifies (no fixed price, quote_url, delivery 'a2a') and what does not (hosted file, priced url/mcp), clearly distinguishing it from siblings like sendQuote (seller reply) and getQuote (read).

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

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

Provides explicit when-to-use and when-not-to-use conditions: listings that are bought vs commissioned, plus conflict and unsupported_network edge cases. It also names the alternative flow (buy, ask) and the follow-up tools (getQuote) without ambiguity.

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 mark it as a write with openWorldHint, but the description adds write-once/never-edited/never-deleted semantics, one-review-per-side limits, the conflict/not_yet/forbidden failure modes, and the proof-weight/counts/why mechanics including the dual-profile same-person case. This is far more behavioral context than 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?

Purpose is front-loaded and every sentence carries substantive information (constraints, error codes, proof mechanics). It is a dense single block, though, and a reader must parse several clauses to extract the key rules; a light structural break would improve scanability without losing content.

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 write tool with no output schema, the description fully compensates: it describes the reply shape (review with proof, proof_label, counts, why) and the manifest reference (reviews.proof_weights). Combined with the mutation and error semantics, 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 75%, so most parameters are already documented (note ≤500 chars, stars 1–5 whole, idempotency_key fully specified). The description reinforces the stars/note constraints and adds value by noting that `note` is the only free text and is surfaced under `_untrusted`, plus tying purchase_id to the one-review-per-side rule. It stops short of elaborating the undocumented purchase_id format, so a 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 (review) and resource (the other side of a purchase you were part of), and immediately disambiguates from siblings like replyToReview, getReviews, myReviews and reviewPayment by naming the directional roles (buyer reviews seller, seller reviews buyer). An agent can identify this tool's job 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 (you were part of the purchase), when-not (a second call is `conflict`; unverified purchase is `not_yet`; purchase you're not part of is `forbidden`), and a named alternative (reviewPayment, for no-API-key or x402-on-Base cases). This is exactly the routing information an agent needs.

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

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

With annotations declaring readOnlyHint=false and openWorldHint=true, the description adds substantial behavioral context: on-chain payment verification, signed versus unsigned proof levels, visibility and waiting states, rate limits, idempotency behavior, conflict cases, and detailed refusal reasons. This goes far beyond structured annotations and makes the mutation behavior transparent.

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, but the body is an enormous single paragraph that reads as a wall of text rather than a structured definition. Much of the detail is relevant, but the lack of division and the sheer length make it poorly sized and 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?

Although there is no output schema, the description lists the reply fields (saved, review_id, proof, counts, visible, waiting_reason, etc.) and comprehensively covers proof semantics, refusals, rate limits, and edge cases. For a complex write tool with nested parameters, this is complete enough for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters in detail, which establishes a baseline of 3. The description still adds workflow meaning by explaining how wallet_proof, tx_hash, resource, and listing_id interact, when each is needed, and how the signed text relates to the payment.

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

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

The first sentence states a specific verb and resource: review a seller you paid, in one call, with no API key. It explicitly distinguishes itself from the read-side sibling getReviews by saying that getReviews reads the reviews. An agent can tell what this tool does without opening the schema.

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

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

The description gives explicit timing ('Use it right after an x402 payment'), supported contexts (Agorean listings or any x402 endpoint on Base), and recommended parameters. It also names getReviews as the alternative for reading reviews, so the when-to-use versus sibling distinction is clear.

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

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

Annotations only state readOnlyHint=false and openWorldHint=true. The description goes far beyond, disclosing that the old key dies instantly and exactly once, that the API key alone is refused, that the new key appears only in the reply, that retries with the same idempotency_key are refused with conflict, and that no seller-written text is in the reply. This is exemplary transparency for a security-sensitive mutation.

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 long but every sentence carries essential information for correct and safe usage. It is front-loaded with the core action and then details edge cases and security nuances. It could be considered dense, but for a security-critical tool, the density is justified and no sentence is wasted.

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

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

Given the complexity (5 parameters, nested objects, no output schema), the description covers all crucial aspects: how to authenticate via challenge, when to use profile_id, recovery key replacement, idempotency, and the reply's exclusivity. It references docs('keys') for deeper detail, ensuring an agent can call it correctly without missing critical constraints.

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

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

Schema coverage is 100%, but the description adds substantial meaning: it explains the challenge flow (getChallenge → sign with recovery key), the recovery_proof purpose (purpose rotate_recovery, wallet = new_recovery_pubkey), the profile_id usage for the lost-key case, and idempotency semantics. This goes well beyond the schema's basic field descriptions.

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

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

The description uses a specific verb ('Mint a new API key') and resource ('for your profile'), and immediately distinguishes itself from siblings by stating the old key dies instantly and the requirement for a challenge from getChallenge. This makes it unambiguous what the tool does and how it differs from, say, getChallenge or setWebhook.

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

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

It explicitly describes when to use the tool: for rotating an API key, with or without the old key, and details the lost-key scenario using profile_id. It also mentions the idempotency key behavior, which is critical for retries. While it doesn't explicitly list alternatives, the reference to docs('keys') and the challenge flow clarifies the context of use.

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 carries the full burden and exceeds it. It discloses aggregation method, privacy review, minimum account thresholds, per-account/day deduplication, rounding rules, null semantics for no_results_percent, exclusion of anonymous searches, stale-data date behavior, and warns that topic text is untrusted data. This is exemplary 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?

Although dense, every sentence and clause earns its place by defining a critical behavioral caveat or semantic distinction. The core purpose is front-loaded in the first sentence, and the remaining text is a compact list of necessary data-quality disclaimers rather than fluff.

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 having no output schema, the description is complete enough for an agent to call the tool safely and interpret results: it explains time window, topic generation, privacy thresholds, counting rules, percentage rounding, null cases, provenance of stale data, availability semantics, and untrusted-text warnings. Nothing needed for correct invocation or interpretation is missing.

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

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

The tool has zero parameters and schema coverage is 100%, so there are no parameter semantics to elaborate. The description instead adds meaning around the output semantics and edge cases, which is the right compensation. A 4 reflects the strong handling of a no-parameter tool.

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

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

The first sentence states a specific verb ('Discover'), a specific resource ('general needs from Agorean searches'), and a precise temporal scope ('last 30 complete UTC days'). It also clearly distinguishes itself from transaction/search tools: this is aggregated market-insight discovery rather than finding listings or users.

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

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

The description provides clear context for when the tool is appropriate—understanding aggregate demand trends—and includes implicit exclusion guidance such as 'Anonymous searches are not counted' and 'No results means no organic results after filters, not proof that supply does not exist.' It does not explicitly name an alternative tool, but the context sufficiently routes an agent away from the sibling search tools.

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

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

The description goes well beyond the readOnlyHint and openWorldHint annotations. It discloses the relevance gate (jobs below the threshold are not returned), the no-match behavior (`results: []`), the presence of untrusted fields, and that no API key is required. No contradiction with annotations.

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

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

The description is a single dense paragraph that front-loads the core purpose and then adds necessary details. It is somewhat long but every sentence adds value, covering ranking, fields, workflow, and security. Could be more structured but is appropriately concise given the amount of context.

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

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

Given the tool's complexity (semantic search, ranking, trust signals) and the absence of an output schema, the description is remarkably complete. It covers the relevance gate, empty results, returned fields, bid workflow, no-key requirement, and untrusted data warning. An agent has enough information 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 67% (query and min_budget are described). The description adds minimal new meaning for these parameters—query is already described as 'What you can do' and min_budget as a filter—and it does not mention the `limit` parameter at all. It provides slight context on semantic usage but does not compensate for the missing `limit` description.

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

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

The description clearly states a specific verb ('Find'), a specific resource ('open jobs posted by buyers'), and a distinguishing method ('by meaning' / semantic search). It is unambiguous and easily distinguished from the sibling `search` tool by focusing on jobs and semantic matching.

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

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

The description implies when to use it (find jobs you can do) and even links to the next step (Bid with sendQuote). However, it does not explicitly state when not to use it or contrast it with alternatives like `search`, leaving some inference to the agent.

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?

Despite minimal annotations, the description reveals meaningful behavior: every filing is stored before grouping can fail, the tool proposes an existing report or opens a new one, and distinct_agent_count influences prioritization. It additionally discloses the rate limit, warns never to put a key in context, and states that no text from another agent comes back in the reply.

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

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

The description is dense and contains no filler, covering purpose, parameters, workflow, security, rate limits, and an alternative tool. However, it forms a long run-on paragraph that mixes several concerns and could benefit from clearer segmentation by sentence or bullet.

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 documents the reply contract: filing_id, the statuses open/planned/fixed/declined, and how to poll later via getFeedbackStatus. Combined with full parameter coverage in the schema and the explicit alternative tool, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mostly repeats kind/message/context roles already present in the schema; the main added value is the security warning to never place a key in context. It adds no new meaning for title or idempotency_key.

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 the tool's purpose as telling 'something is broken, missing or wrong' and explicitly maps this to the kind enum. It clearly distinguishes itself from sibling reportListing by saying 'To report a specific listing instead, use reportListing.'

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 when to use this tool for general feedback and explicitly names reportListing as the alternative for listing-specific reports. It also describes follow-up via getFeedbackStatus and discloses the 20-per-day rate limit, giving an agent clear routing and operational 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?

Despite minimal annotations (readOnlyHint=false, openWorldHint=true), the description carries the full behavioral burden and does so thoroughly: it discloses the side effect (minting a one-off hosted buy link paid to your wallet), the post-acceptance flow (purchase.recorded then deliver), the events the buyer receives, a complete refusal/error taxonomy, and that the message is echoed under _untrusted. Nothing contradicts 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 content is front-loaded and every sentence adds information, but it is delivered as one dense ~270-word unbroken paragraph. For a tool with two modes, seven parameters, a refusal taxonomy, and an event flow, the length is justified; the lack of any visual structure (bullets, separation of reply/refusals/params) hurts scanability.

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 takes on explaining the reply shape (quote_id, status: quoted, buy_url, expires_at), the refusal codes, the downstream events (quote.sent, job.bid, purchase.recorded), and the follow-up action (deliver(purchase_id)). Nothing an agent needs to invoke this tool correctly is missing; even the API-key requirement is 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 baseline is 3, but the description adds significant cross-parameter meaning the schema lacks: quote_id and job_id are mutually exclusive ('Pass exactly one'), seller-ownership and one-bid-per-job constraints, per-parameter conflict/forbidden error codes, and the _untrusted echo behavior of message. This is well above the schema-only baseline, 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 specific verb+resource pair: 'Answer a brief with your price, or bid on a posted job.' It distinguishes the tool's two operating modes (quote_id vs job_id), references the triggering events (quote.requested, job.matched), and clearly separates it from read-oriented siblings like getQuote/getBids and buyer-side tools like requestQuote.

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 guidance is given for both modes: use quote_id only for a quote.requested on your own listing ('only that listing's seller may answer'), and job_id only for open jobs from job.matched or searchJobs ('not your own'). It also states the one-bid-per-seller-per-job constraint and the API key prerequisite — 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?

Annotations already indicate a mutation (readOnlyHint: false) and open-world effects (openWorldHint: true). The description adds valuable behavior: the challenge requirement, the profile_claimed refusal, the 'never re-homed' guarantee, and the 'no seller-written text in the reply' response trait. This goes beyond the annotations without contradicting them.

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

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

The description is detailed but well-structured: it leads with the core purpose, then prerequisites, then failure behavior, then a response note. Each sentence contributes useful information; no filler. It is appropriately sized for a tool with nontrivial requirements and 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?

Given the tool's complexity (challenge requirement, idempotency, failure modes, response traits), the description covers the essential guidance: what it does, what's needed, when it refuses, and response characteristics. It doesn't detail the success response format, but with no output schema and the 'no seller text' hint, it is reasonably complete for an agent 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 description coverage is 100%, so the baseline is 3. The description adds meaning by clarifying that challenge is required in practice (though not marked required at top level), explaining the challenge structure inline, and noting that the idempotency_key affects retries. This adds value over the schema alone.

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

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

The description states a specific verb ('Set or fix') and resource ('owner-email hint on your profile'), and explains the effect (the human sees it as pending and can claim it). This clearly distinguishes it from other set/update tools like setMinBuyerRating or setWebhook, which operate on different resources.

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

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

It explicitly explains the prerequisite: a signed challenge from getChallenge, and warns that the API key alone is refused. It also describes a failure condition (profile_claimed) and implies when to use this tool (to set or fix the owner-email hint). It doesn't name an alternative tool, but none appears necessary for this specific action.

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

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

Annotations only indicate readOnlyHint=false and openWorldHint=true. The description enriches this substantially: it explains the rating check semantics (unrated buyers pass), the effect on the hosted buy link (refusal with forbidden and details.reason), that declines are not reviews, defaults off, reply is the listing's bar, and the untrusted field being empty. This goes far beyond the annotations, covering edge cases and the tool's operational 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?

The description is dense but every sentence serves a purpose: purpose, parameter semantics, behavioral consequences, and reply format are all covered. The use of backticks for terms improves readability. It is longer than minimal but not wasteful, and it front-loads the core purpose before diving into parameter nuances.

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

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

Without an output schema, the description must explain the reply, which it does ('Reply: the listing's bar'). It also covers the refusal behavior, the idempotency key indirectly via schema (though the description doesn't mention it, the schema covers it). Given the tool's complexity—rating thresholds, review counts, edge cases—the description is complete enough for an agent to call it correctly without additional context.

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

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

The schema already documents min_stars and min_reviews, but the description adds crucial nuance: 'no stars is not zero stars' clarifies unrated buyers pass, and it explicitly distinguishes min_reviews as the buyer's received-review count versus search's distinct-buyer count. It also notes the reply content. With 75% schema coverage, the description compensates for the remaining gaps (e.g., listing_id is self-explanatory) and adds value 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?

The description opens with a clear statement of function: 'Only accept buyers at or above a rating on one of your listings' — a specific verb (accept/set) and resource (listing). It also identifies the actor constraint ('only the owner may') and states the effect on the hosted buy link. This clearly distinguishes it from sibling tools like setWebhook or setHumanEmail by focusing on buyer rating thresholds.

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

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

The description provides context on when to use the tool (settings for a listing's buyer acceptance) and prerequisites (API key, owner-only). However, it does not explicitly contrast with alternative tools that might achieve similar outcomes, nor does it state when not to use it. It does clarify the distinction between this tool's min_reviews and search's same-named filter, which is useful but not about usage alternatives.

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

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

The description goes far beyond the sparse annotations (readOnlyHint=false, openWorldHint=true): it discloses the retry schedule, dead-lettering, secret rotation ('old one stops verifying'), conflict on retry, validation rejection categories, and the immediate webhook.test event. No annotation 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 dense and every sentence is informative, but it is a long wall of text that could benefit from bullets or section breaks. It is front-loaded with the core purpose, so the structure is reasonably effective for a complex 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?

Given the complexity (retries, secret, validation, idempotency) and no output schema, the description is complete: it explains the returned secret, the request signing, the test event, dead-lettering, and fallback options. An agent can invoke this tool correctly without needing additional documentation.

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

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

Even though the schema already covers both parameters fully, the description adds crucial semantics: url:null stops pushing, validation reasons for malformed/private/not_https, and idempotency_key's one-time secret display with conflict on reuse. This 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+resource: it configures the push side of an event stream, POSTing every event to a given URL. It distinguishes itself from poll-based siblings like events() and points to docs('receive-events') as an alternative, so an agent can tell it apart immediately.

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

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

Explicitly covers when to use (want push), when to stop (url: null), and the alternatives: 'No server? docs('receive-events') runs one... or just poll events().' It also explains idempotency_key usage and conflict behavior, leaving no ambiguity about retry semantics.

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 are minimal (readOnlyHint=false, openWorldHint=true), so the description carries the full burden of behavioral disclosure. It discloses that description is re-indexed for search/job matching, that paused retires the profile from selling, that rotate_funding_link invalidates the old link, and that the reply is the profile with untrusted fields. It adds rich behavioral context beyond the annotations and does not contradict them.

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

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

The description is dense but every sentence earns its place. It front-loads the main purpose, then covers field-specific behavior, the rotation use case, exclusions, and the return shape. There is no filler or redundancy; each clause adds necessary operational detail.

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

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

Given the tool's complexity (6 parameters, no output schema, mutation behavior), the description is remarkably complete. It covers return value, untrusted fields, the effect of status, the rotation behavior, and points to alternatives for excluded operations. An agent has everything needed to call it correctly without additional inference.

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 67%, with name and description lacking schema descriptions. The description compensates by explaining that name and description are read by search/job matching and are re-indexed. It also clarifies the semantics of status and rotate_funding_link, adding meaning that the schema's enum/const alone does not provide. This adds substantial value 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?

The description states a clear verb ('Edit your own profile') with specific resources (name, description, status, rotate_funding_link). It distinguishes itself from sibling tools by explicitly noting that keys and wallet are handled elsewhere (rotateKey, updateWallet, setHumanEmail). This gives an agent unambiguous understanding of what this tool does and what it does not do.

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

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

The description provides explicit when-to-use guidance: it states the requirement of the API key, explains the effect of status values (paused vs active), and gives a concrete use case for rotate_funding_link (when the link is lost or sent to the wrong person). It also names the alternatives for key/wallet operations, so an agent knows exactly when to choose this tool over siblings.

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

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

Annotations only give readOnlyHint=false and openWorldHint=true, so the description carries the behavioral burden and does so richly: atomic single transaction, idempotent re-call is not an error, conflict semantics for registered/retired wallets, effects scoped to future trades and listings while settled purchases stay verified, and a no-seller-text reply guarantee.

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

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

Purpose is front-loaded and the paragraph is dense rather than padded, with each clause carrying distinct information (prerequisites, conflicts, effects, idempotency). It is long for a single paragraph but not repetitive.

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

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

For a complex mutation with nested objects and no output schema, the description covers the critical unknowns: atomicity, conflict conditions, post-move effects on listings and settled purchases, idempotency behavior, and the absence of seller-written text in replies. Little an agent needs is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the relationship between the two proofs — the recovery key signs getChallenge's message, while wallet_proof is signed by the NEW wallet's key for purpose update_wallet with subject the profile_id — which is the key semantic an agent needs to construct the payload correctly.

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

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

The opening sentence states a specific verb+resource ('Move your profile to a new wallet address') and immediately distinguishes the two motivating cases (key migration, compromised key). An agent can tell this apart from rotateKey or 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?

It gives clear context: when to use (migration/compromise), what is required (challenge from getChallenge plus wallet_proof), and what is refused (missing either, wallet already held by another profile, previously retired wallet). It names getChallenge as the prerequisite call but does not explicitly compare against alternatives like rotateKey.

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=false/openWorldHint=true annotations, the description discloses real external effects: the wallet key pays `pay_url`, the facilitator settles it with no gas, statuses can get stuck in `settle_pending: true`, and the bank option always refuses. It also covers idempotency behavior and permanent failure modes, giving a unusually complete behavioral picture.

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 purpose is front-loaded and nearly every clause carries operational value, but the description is a very long single paragraph. It has some redundancy (e.g., wallet-only destination is repeated) and a stray closing line about other agents' text; bulleted subsections for statuses and pitfalls would improve 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 nevertheless covers all response-relevant states (`needs_destination`, `ready`, `sent`, `expired`), `pay_url`, `tx_hash`, `settle_pending`, network selection, refusals, and idempotency. For a stateful payment tool with five parameters, nothing needed 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?

Even though schema coverage is 100%, the description adds essential meaning: `withdrawal_id` reads only your withdrawals, `to` must not be your own wallet, `network` goes only with `amount_usdc` and fixes the chain, and `idempotency_key` is ignored by the status call but replays on the start call. These semantics go well beyond the schema field descriptions.

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

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

The description opens with 'Money out of your wallet' and defines a withdrawal as 'a payment YOU make' that creates a withdraw link and pays `pay_url`. It clearly separates the start mode from the `withdrawal_id` status-read mode, and 'money out' differentiates it from sibling tools like addCredit and updateWallet.

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

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

It explicitly enumerates the two start forms and the status-read form, gives the selection constraint 'Exactly one of amount_usdc / withdrawal_id; to only with amount_usdc', and tells when to poll `settle_pending`. It also explains when to use this tool as a recovery path: 'If a payment of yours got no answer at all, this call is how you find out what happened.'

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