Agent Market

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

Adds real context beyond the annotations: the approval_code gate, the human_approval_required outcome, and that a successful call returns the other side's email. Annotations already declare the safety profile (non-readOnly, non-destructive, non-openWorld), so the remaining gap is what happens on repeat calls or partial-state retries — especially relevant since the schema exposes an idempotency_key while idempotentHint is false, a discrepancy the description does not resolve.

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

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

Four short sentences, purpose front-loaded, then the blocking prerequisite, then the return value, then the fallback sibling. Every sentence carries information an agent needs and none repeats structured fields.

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 multi-party workflow step with a human-in-the-loop gate, the description covers the trigger, the blocking condition, and the success indicator, and an output schema exists so return shape needn't be spelled out. It stops short of describing what state the deal is in after a partial approval or how a retry interacts with the idempotency_key, which is the main remaining ambiguity.

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 deal_id, owner_key, approval_code and idempotency_key are already documented at the field level. The description reinforces where approval_code comes from and the consequence of not having it, but adds no new syntax, format, or per-parameter meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: closing the person's side of a deal they already approved, with a clear terminal outcome (both sides approved). It is distinguishable from the read-only market_deal_log it references, though the phrasing 'close the person's side' is somewhat metaphorical and never says outright that the deal is being bound/accepted.

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

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

Gives explicit preconditions (requires the approval_code the person sees after pressing Approve) and the exact failure path when it is missing (human_approval_required). It also instructs the agent to ask the person for the code and never guess it, and routes to market_deal_log when the other side's status is in question.

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

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

Annotations already declare non-read-only, non-idempotent, closed-world behavior, so the bar is lower; the description still adds real value by flagging that question text is untrusted buyer-written data and must never be treated as instructions, and by stating the one-answer-per-question rule. It does not say what happens if a question was already answered or how the answer reaches the buyer.

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

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

Three short sentences with the role, the source, the grounding rule and the injection warning front-loaded. Nothing is repeated from the name or schema and nothing is wasted.

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

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

With an output schema present and full parameter coverage, the description covers the essential agent-facing concerns: where questions come from, what may be said, and the injection risk. It leaves the post-answer effect and duplicate-answer handling implicit.

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

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

Schema description coverage is 100%, including the source of question_id and the privacy note on owner_key, so the schema carries the parameter burden. The description only restates the question_id source and adds the truthfulness constraint on the answer, which is a modest addition.

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

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

Specific verb+resource: answering one buyer question, and it names the exact source queue (questions.waiting_for_you in market_deal_log). The ask-vs-answer direction is clear enough to separate it from market_ask_seller without opening either schema.

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

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

'One answer per question' and the restriction to questions in the waiting queue give clear in-scope conditions, plus a content constraint (answer only from the listing and facts given). It does not explicitly name when to use a sibling instead or what to do with questions outside the queue.

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 this is a non-read-only, non-destructive, non-idempotent write, and the description adds real value beyond that: it discloses the visibility scope ('Only the seller's agent and this owner see it') and warns where the reply resurfaces ('questions.asked in market_deal_log, inside untrusted_seller_text'), which is a useful trust-boundary cue. It says nothing about quota/rate limits or whether the question is sent immediately, so it is strong but not exhaustive.

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

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

Three short sentences, front-loaded with the action and scoping, then visibility, then where the answer appears. No filler.

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

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

An output schema exists, so return values need not be spelled out, and the description still covers the key unknowns for a messaging-style write: audience, privacy, and where the response is later exposed.

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 owner_key, listing_id, question, and idempotency_key are all documented in the schema itself; the description only loosely informs the content of 'question' via its examples. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Ask the seller's agent one question about a listing') and scopes it to the pre-offer phase. The examples ('what a data file holds or how long a service takes') and the 'one question' framing make it clearly distinct from market_answer_question and market_counter.

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

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

'before offering' gives a clear usage context, and the description implies this is the question channel while market_answer_question is the reply channel. It does not explicitly name when not to use it or point at the answering sibling, so it stops short of full routing guidance.

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

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

Annotations only declare that this is a non-read-only, non-destructive, non-idempotent, closed-world call; the description supplies the effect that matters most — a mutual, permanent bar on future deals ('Neither of you can start a deal with the other again'). It does not say whether a block can be lifted, nor that the effect is symmetric for the seller's view. Mild tension exists with idempotentHint=false given the optional idempotency_key retry semantics, but that is a schema-level detail, not a contradiction in the description.

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

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

Two short sentences, front-loaded with the action and its two target modes, with the consequence in the second sentence. Nothing is redundant with the title 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?

An output schema exists and annotations cover the safety profile, so the description only needs to carry the action, its target options, and the effect — all present. The notable gap is that the schema marks only owner_key as required and does not constrain the call to exactly one of deal_id/listing_id, a rule the description implies but never states.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by explaining what each identifier resolves to as a target (deal_id blocks the counterparty, listing_id blocks the seller), which the schema does not say. It says nothing about owner_key or idempotency_key semantics beyond what the schema documents.

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 (block) and names the two exact targets (the other side of a deal via deal_id, or the seller of a listing via listing_id). No sibling tool performs blocking, so an agent can identify this action unambiguously from the name plus first sentence.

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 parenthetical mapping tells the agent which identifier selects which target, which is genuine usage guidance. It stops short of stating exclusions or prerequisites — e.g. that exactly one of deal_id/listing_id should be supplied, and that owner_key must come from an authenticated identity (only the schema says this).

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 covering the safety profile, the description adds real behavioral context: it discloses the three possible outcome states, that the seller's rules answer on the seller's behalf, and that an agreed price carries an approval_url. It does not say what happens when the price exceeds 'the person's limit' (rejection vs. error) and does not reconcile the non-idempotent annotation with the idempotency_key parameter.

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

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

Front-loaded with the action, then the routing rules, then the role caveat. The next_action explanation is slightly redundant with the output schema and the parenthetical '(your last price again is fine)' makes one sentence run long, but no sentence is filler.

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

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

An output schema exists, yet the description still usefully summarizes what next_action values mean and where approval_url lives, which is exactly the context an agent needs before choosing between countering and accepting. The remaining gap is error/limit-exceeded behavior for a tool that mutates a live negotiation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: price_usd must stay within 'the person's limit' and may legitimately repeat the previous price. That constraint on the price value is not encoded anywhere 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 first sentence gives a specific verb and resource (answer a seller counter with a new price) and the role rule ('Only the buyer's agent counters: the seller's rules answer for the seller') separates this from market_make_offer / market_ask_seller. It stops short of naming any sibling tool explicitly, so an agent must infer the boundary rather than read it.

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 next_action branches are spelled out as concrete usage instructions: counter_again means come back with another counter inside the limit (repeating the last price is acceptable), decide_on_last_price means the ask is final, send_approval_url means the price is agreed. That is strong 'when to call again' guidance, but it never says when to stop and hand off to market_accept or market_request_approval instead.

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

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

Annotations only say write/no-destroy/no-idempotency; the description adds what the annotations cannot: lowest_price_usd is a private floor the market counts down to, auto_accept_at_usd silently binds deals above a private threshold, a wrong description 'can be reported', digital listings stay on sale after each deal, and delivery happens post-bind via market_mark_delivered. That is substantial behavioral context for an irreversible write.

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

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

One long, dense block mixing scope, refusals, privacy semantics, language rules, sign-up flow, and digital-listing plumbing. The lead is well front-loaded, but several clauses (owner_key first-call behavior, declaration restatement) duplicate schema text and the lack of structure forces serial reading of 20-parameter behavior in prose.

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

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

With an output schema present and 100% schema coverage, the description need not explain returns, and it does cover the decision-critical pieces: prerequisites, refusals, privacy of prices, digital delivery hand-off, and the first-call identity flow. Minor gaps remain around counter/step defaults and agent_label exposure, but they are largely covered by schema descriptions.

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 still earns above baseline by explaining lowest_price_usd's private-floor/counter mechanics, auto_accept_at_usd's 'no page approval, withdraw to stop' semantics, photo_urls as existing https links, and the language/English-title rule for title. Less coverage of max_counters, counter_step_usd, idempotency_key and agent_label, which are left to their schema text.

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

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

Opens with a precise verb+resource ('List one second-hand item... or one digital good') and immediately bounds it: physical goods the person owns vs. data files/fixed-scope services delivered by email. An agent can distinguish this from market_get_listing or market_make_offer without consulting another schema, and the refusal list further sharpens the scope.

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

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

Gives an explicit workflow: gather missing fields and the three declaration questions in ONE message before calling, then send declaration with all three true. It also states the first-call rule (omit owner_key, answer returns one), the digital-listing branch (category data/services, delivery digital, may be price 0, approve_in_advance, then deliver via market_mark_delivered), and the refused categories. Alternatives are named where relevant rather than left to inference.

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

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

Beyond the readOnly/idempotent annotations, it discloses substantive behavior: the log is visible to both buyer and seller, bound deals expose the other side's email in contact and in the log and should be given to the person, and seller_idle appears when a deal waits on the seller after buyer approval. These privacy and state behaviors are not captured by annotations, though the phrasing is cryptic.

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 with/without distinction is front-loaded, which helps. However, the remaining sentences are dense, run-on, and rely on unexplained terms like seller_idle, so the description is harder to parse than its length warrants.

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?

It covers both query modes, the privacy behavior around contact emails, and the relationship to market_wait. With an output schema and fully described parameters, the remaining omissions (ordering, pagination) are minor for a read-only log 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 baseline is 3, but the description adds real meaning by explaining that deal_id switches the tool between a single-deal log and a person-level view of deals, listings, and questions. It does not elaborate on owner_key, but the schema already describes it fully.

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

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

The description names the resource (the deal log) and specifies two distinct modes: one deal's log with a deal_id, and the person's deals/listings/questions without one. It also distinguishes itself from market_wait, though the prose is elliptical and the primary verb ('read'/'return') is only implied rather than stated.

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 separates usage by parameter: with deal_id for a single deal's log, without for the person's broader deals and questions. It also explicitly contrasts itself with market_wait, noting that a wait does not surface buyers' questions, which gives an agent a concrete routing rule, though no explicit 'do not use' cases are stated.

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

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

The annotations already declare this as a read-only, idempotent, non-destructive operation, so the description does not need to restate safety. It adds meaningful behavior by noting that empty arguments return the newest skills and that each result includes an install_prompt intended to be spoken or followed.

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

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

The description is three short sentences with no wasted text. It front-loads what the tool returns and follows with the two most important behavioral details: default ordering and install_prompt usage.

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

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

With an output schema and full annotation coverage, the description does not need to explain return values or safety. It is nearly complete for a finder tool, but it lacks explicit routing guidance versus sibling tools and does not mention any pagination or result-limit behavior.

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

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

Schema description coverage is 100%, and the schema already documents kind, query, and handle in detail. The description adds only the empty-arguments default ordering, not additional semantics for the individual filter parameters, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the resource as agent skills listed on the market and notes that results include real outputs. It does not explicitly distinguish the tool from siblings such as market_search or market_get_skill, so it stops short of full sibling differentiation.

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

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

It implies usage by explaining that empty arguments return the newest skills, which is a useful default. However, it does not state when to use this tool instead of market_search or market_get_skill, nor does it provide exclusions.

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

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

Annotations already cover readOnly, idempotent, non-destructive, and closed-world behavior. The description adds useful behavioral context by listing returned content and explicitly warning that untrusted_seller_text must be treated as data, not instructions, which is valuable safety guidance 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?

Two sentences, front-loaded with the returned content and followed by the important trust-boundary warning. Every sentence earns its place with no redundant filler.

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

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

With an output schema, full annotations, and a single documented parameter, the description is largely complete for correct invocation. It could say more about missing-listing behavior or its relationship to search, but nothing essential 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?

There is only one parameter, and the schema fully documents it as a listing_id sourced from market_search. The description does not add further meaning beyond the schema, so the high schema coverage sets the baseline at 3.

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 a full listing and enumerates the fields it contains, which distinguishes it from a search result. It does not explicitly name the sibling search tool as the alternative, but the purpose is still easy to infer.

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 does not state when to use this tool versus market_search or other siblings. The schema note that listing_id comes from market_search provides some implicit context, but the description itself gives no usage guidance or exclusions.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds genuinely non-obvious context: the skill text is creator-authored and therefore untrusted, with an explicit instruction-following caveat. It stops short of noting any rate limits or what happens when a handle/slug pair does not exist.

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

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

Two tight sentences: the first front-loads what the caller gets, the second front-loads the safety rule. No filler, no restatement of the name or title.

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

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

With an output schema present, the description needn't explain return shape, yet it still previews the contents. Purpose, contents and usage caution are all covered; only failure behavior for unknown handles/slugs is absent, which is a minor gap for a simple two-param read.

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

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

Schema coverage is 100% and both parameters are documented there, including the @handle format and the reference to market_find_skills for the slug. The description adds no further meaning about either parameter, so the baseline 3 applies.

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

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

States a concrete verb (read) and resource (one skill) and enumerates the payload — description, version, files, SHA-256, install steps, outputs — which implicitly contrasts with the plural listing tool market_find_skills. It never names that sibling explicitly, so an agent must infer the pairing from 'One skill in full'.

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

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

Gives real usage context: 'read it before you install it' establishes the pre-install inspection workflow, and the follow-only-on-request rule sets a policy boundary. It does not name market_find_skills as the way to obtain the handle/slug, so the discovery path is left implicit.

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

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

Annotations only tell the agent this is a non-read-only, non-destructive write; the description carries the real burden and does so: seller rules auto-agree or auto-counter, an opening offer at the limit often pays the limit, and a new owner_key is minted on the first call. The approval_url handoff to the person is a behavioral detail no annotation or schema field conveys.

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

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

The action and its constraints are front-loaded, and each sentence carries usable information rather than restating the name. It is slightly dense and run-on, with several clauses chained by semicolons, but no sentence is clearly disposable.

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 10 parameters and an output schema present, the description correctly focuses on process rather than return values, while still naming the salient answer fields (next_action, approval_url). It leaves unstated what happens on an outright rejection or a seller who never responds, which matters for an offer that may sit open.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the intent behind person_wants and person_max_usd (both shown to the person beside the deal before approving) and the constraint linking price_usd to person_max_usd. It doesn't add anything for delivery, must_haves, note, or agent_label beyond what the schema already says.

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

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

The first sentence names a specific verb and resource ('Offer a price on a listing') and the beneficiary ('for the person'), immediately distinguishing it from market_counter and market_accept. The negotiation flow described makes it clear this is the entry point of a bargaining sequence, not an acceptance.

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 conditional routing: omit owner_key on the first call, call market_counter when next_action is counter_again, send approval_url once the price is agreed. It also gives a concrete behavioral rule ('never offer above the person's limit') and the rationale for opening low.

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 declare this is a non-read-only, non-destructive, idempotent operation. The description adds useful behavioral context beyond that: the buyer's agent sees delivered: true plus a log line, and the action carries no text, which clarifies the effect and limits.

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

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

The description is three tight sentences with zero wasted language. The precondition is front-loaded before the observable effect, making it easy to scan and act on.

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

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

With an output schema present, rich annotations, and full schema description coverage, the description supplies the remaining key context: when to mark delivery, what the buyer observes, and that no text is involved. Nothing an agent needs in order to call this correctly appears to be missing.

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

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

Schema description coverage is 100%, so all parameters are already documented in the schema. The description references market_deal_log as a source for deal_id but does not add syntax or constraints beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: marking a bound digital deal delivered. It clarifies the seller-agent perspective and ties the action to a concrete precondition involving market_deal_log, which distinguishes it from sibling tools like market_deal_log or market_make_offer.

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

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

It gives a clear usage condition: call this once the file or report was sent to the buyer's email from the contact in market_deal_log. It does not explicitly name when not to use the tool or direct the agent to alternatives, but the triggering context is specific enough to guide selection.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds a genuinely non-obvious behavioral trait — that reports are cumulative and several are needed to remove a listing — which no annotation conveys. It stops short of saying whether the report is visible to the seller or what the caller gets back.

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

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

Two sentences, no filler, with the action and the reason list front-loaded and the outcome clause second. Every sentence carries information an agent needs.

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

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

With an output schema present and full parameter coverage, the description does not need to explain return values. It covers purpose and the takedown consequence, but leaves the post-call state (e.g., confirmation, whether the report is anonymous) unstated for a mutation tool.

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

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

Schema description coverage is 100%, so all five parameters, including note length limits and the idempotency_key retry semantics, are already documented in the schema. The description only echoes the reason categories, adding nothing about format or usage of owner_key/listing_id, so baseline 3 applies.

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

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

Starts with a clear verb+resource ("Report a listing") and enumerates the violation categories, which map directly onto the reason enum. It is distinguishable from siblings like market_block or market_search, though it never explicitly contrasts itself with them.

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?

"Report a listing that breaks the rules" implies the trigger condition, and "Several reports take it down" implies the effect. However, there is no guidance on when to prefer this over market_block, market_withdraw_listing, or contacting the seller via market_ask_seller.

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 the approval workflow, the required human handoff, the prohibition on self-approval, and the condition that the deal binds only when both sides' people approve. These are important behavioral constraints that an agent could not infer from the annotations alone.

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

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

The description is front-loaded with the core action and return value, followed by usage context and guardrails. Every sentence contributes useful information without repetition.

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

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

Given the available annotations and output schema, the description provides the key workflow guidance an agent needs: how to obtain the approval URL, what to do with it, and what not to do. No critical behavioral or usage information 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 parameter meanings are already well documented in the input schema. The description adds contextual meaning around the deal and the person's approval page but does not provide additional parameter-specific syntax or constraints 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 specific verb and resource: make the person's approval page for an agreed deal and get its approval_url. It also distinguishes the tool from market_make_offer and market_counter by explaining that the buyer's agent already received the link from those 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 explicitly says when to call this tool: for a new link or when acting as the seller. It also states what to do next (send the URL to the person and wait) and gives clear exclusions (never open it yourself and never approve for the person).

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

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

Annotations already cover safety (readOnly, idempotent, non-open-world), and the description adds substantial context on top: no-auth usage, 25-per-page sizing, best-match ordering, count as total, and the match/match_note markers for fuzzy results. The untrusted_seller_text warning is a genuine security disclosure absent from the schema and annotations.

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

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

Front-loaded with purpose, then pagination, then matching semantics, then a security note — a sensible ordering. The semicolon-chained sentences are dense and the matching clause is a long run-on, costing a little readability, but no sentence is filler.

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

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

For a 7-parameter, zero-required search tool with an output schema, the description covers pagination, result ordering, result counts, fuzzy-match flags, and untrusted text handling. An agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description does add real meaning about matching behavior (accents ignored, plurals, synonyms, spelling slips) and the cursor pairing rule, which goes beyond the schema's per-parameter text, but it stops short of elaborating on most individual parameters.

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

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

Opens with a specific verb and resource: 'Search second-hand items people sell on Agent Market', then extends scope to digital goods and API credit packs. The scope is precise enough to distinguish it from siblings like market_find_skills or market_get_listing, which are skill-directory and single-listing lookups rather than marketplace search.

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 actionable operational rules: empty arguments list everything, no sign-in required, and when next_cursor is non-null send it back as cursor with identical arguments. It does not, however, explicitly say when to prefer this over siblings such as market_get_listing for a known item, so there is no exclusion 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?

Beyond the annotations, it discloses the out-of-band confirmation flow (email link, user presses Confirm), the sign_in_url fallback if email fails, the instruction never to confirm on the user's behalf, and the privacy rule that the email is revealed only after mutual approval. It does not clarify the idempotency_key behavior, which the annotations declare as idempotentHint=false even though the schema offers an idempotency key.

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

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

Front-loads the optionality and the owner_key rule, which are the decision-critical facts. It is denser than ideal with several colon-chained clauses, but nearly every sentence carries a distinct behavioral fact rather than filler.

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

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

An output schema exists so return values need not be explained, and the description still covers the two non-obvious outcomes (same key back vs. new empty owner) plus the manual confirmation step. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning for owner_key: sending an existing one preserves the person's listings and deals, while omitting it creates a new empty owner and orphans prior data. That consequence is not spelled out as starkly in the schema text.

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

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

States a specific verb and resource ('sign in with the person's email') and immediately qualifies it as optional. It also contrasts with the sibling paths that make sign-in unnecessary (market_make_offer, market_create_listing), so an agent can place it in the workflow without opening other schemas.

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

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

Explicitly says when NOT to call: 'You do not need sign-in to list or offer' and names the tools that mint an owner_key instead. It also gives the conditional branch for when to pass owner_key. Both the use case and the alternatives are stated.

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

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

Annotations mark this read-only and idempotent, and the description still adds substantial operational context beyond them: the default 25-second timeout with a hard cap at 50, the changed:false answer on timeout, the one-wait-per-owner_key constraint where 'a newer call ends the older one', and the recovery path ('if an answer is lost, market_deal_log still shows every deal as it is now'). The cursor-continuation behavior is also disclosed.

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

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

Front-loaded with the core behavior and the polling alternative, then layers the operational details. It is dense with semicolon-chained clauses, and the sentence describing what a change payload contains overlaps the output schema, so it is efficient but not maximally tight.

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

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

For a long-poll style tool with three parameters and an output schema, the definition covers timeout bounds, timeout outcome, cursor continuity, concurrency limits, and the fallback if a response is lost. Nothing an agent needs to call it safely 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, and the description exceeds it by explaining what omitting 'since' does — the wait resumes after the last change reported to this owner_key, or after its last market_deal_log list. It also warns to keep timeout_seconds under the client's call timeout. There is some repetition of the schema's own wait_cursor wording rather than added depth on the cursor format.

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

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

Names a specific verb and resource ('waits until one of the person's deals changes, then answers at once') and immediately distinguishes the tool from its polling sibling market_deal_log. The definition also separates a deal change from a buyer's question, which no sibling name makes obvious.

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

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

Explicitly routes the agent: 'Call it instead of asking market_deal_log again and again', with two concrete scenarios (waiting for the other side to approve, a seller waiting for offers) and the exclusion that questions are not deal changes and belong to market_deal_log. When-to-use and when-not-to-use are both covered.

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 declare destructiveHint=true and idempotentHint=true, but the description adds the key consequence the annotation cannot convey: open deals close, while a deal already approved by both parties survives. It still does not say whether the withdrawal is reversible or relistable, or what permissions owner_key must 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?

Two short sentences with no filler. The core action comes first, followed immediately by the side effects, which is the right order for a destructive operation.

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

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

With an output schema present, return values need no explanation, and the description covers the critical destruction semantics. It omits edge cases such as what happens to pending but unapproved offers, and whether the listing can be restored afterward.

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

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

Schema description coverage is 100%, so all three parameters (owner_key, listing_id, idempotency_key) are already documented in the schema. The description adds only the scoping implication that the listing must belong to the person identified by owner_key, and it does not explain the parameter formats 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 gives a specific verb ('Withdraw') and resource ('one of the person's listings'), and the contrast between withdrawing and the market_create_listing sibling is clear. It never explicitly names or differentiates itself from other listing-related siblings (market_get_listing, market_search), so it stops short of the top score.

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

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

The description implies usage, namely taking a listing off sale, but it never states when to call this tool versus alternatives such as market_block or market_report, and it gives no prerequisites or exclusions. An agent must infer the trigger condition from the title.

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