XP Tickets

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

Beyond the destructive annotation, it discloses the real consequences: acceptance starts a per-sale deadline, missing it can cancel the sale and forfeit payout, and acceptance is irreversible. It also names the auth and write:listings scope requirements and explains the two-phase result semantics.

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

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

The description is front-loaded with the main consequence and required flow, and most sentences carry useful operational detail. It is somewhat long and repetitive, especially around seller-facing context and the preview/confirm warning, but not wasteful enough to obscure the core instruction.

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 destructive annotation, output schema, and fully described input schema, the description fills the remaining gaps an agent needs: irreversible consequence, deadline handling, auth/scope, and the preview-then-confirm protocol. Nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds important meaning for confirm: false previews the accepted offer, true actually accepts it, and only true returns success. It adds less for identifier and offer_uuid because the schema already documents their sources.

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

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

The description states a specific verb and resource: a seller accepts a buyer's offer on their listing. It clearly distinguishes the action from adjacent seller tools like reject_offer and from buyer-side actions by saying the offer comes from the buyer, not XP.

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

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

It gives explicit when-to-use guidance (authenticated seller accepting a specific bid on their listing) and a required two-phase flow: preview with confirm=False, then confirm=True only after explicit user approval. It also explicitly warns not to use it without that flow.

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 this is a non-readOnly, non-destructive, closed-world write; the description adds genuinely non-obvious behavior: dedupe by linking an already-listed feed to this node instead of duplicating, and public feeds being shared fleet-wide unless auto-approval is off. That is real added context beyond the annotations, though permission requirements and failure handling are still unstated.

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 scoping sentence is front-loaded and each subsequent sentence carries distinct information (immediate availability, auto-approval caveat, dedupe behavior). The inline return-shape bracket is the one piece that could be trimmed given an output schema exists.

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

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

For a mutating, non-destructive tool with a full input schema and an output schema, the description covers the pieces an agent can't infer: immediate searchability, dedupe-on-existing, and public-share/auto-approval behavior. The prose return shape duplicates the output schema and rejection causes remain vague, but nothing critical to invoking 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% and the sources array already documents platform, source_kind, target, access_type and the 20-item cap, so the schema does the heavy lifting. The description adds no semantics for agent_name (separate tracking per name) or for how target formats map to source_kind, leaving the baseline 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?

States a specific verb and resource ("Add feeds this node can read") and narrows scope to groups the person belongs to or searches they run. An agent can tell this registers existing feed sources rather than searching or discovering them, though it never names the closest sibling (submit_discovered_sources) to sharpen the boundary.

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

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

"They are this node's to search right away: get_listening_assignment starts handing them out" gives useful sequencing context, and the auto-approval caveat hints at a precondition. But there is no explicit statement of when to use this over submit_discovered_sources, or what to do when a source is rejected.

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 cover read-only safety, but the description adds real behavioral context beyond them: calling it early can swallow the 401 that would otherwise start OAuth, and the response never contains raw tokens. This is a non-obvious side effect that an agent could not infer from the schema or 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?

It is front-loaded with the 'Use ONLY when' rule, and every sentence adds something useful. The example list and the long list of protected tools make it dense, but none of it is padding, since those lists are what make the routing rule actionable.

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 an output schema exists, the description still briefly states the shape of the result (authenticated boolean, tier roles, wallet flag, no raw tokens), and it fully covers the routing and OAuth behavior that make this tool easy to misuse. Nothing an agent needs in order to call it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing to explain and the baseline is 4. The description correctly says nothing about inputs and instead spends its words on when to call the 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 states a specific verb and resource: check whether the user is signed in to the XP marketplace. It clearly distinguishes this tool from all the protected siblings (account, my tickets, wallet, favorites, referral, order tools) and names exactly what state it reports.

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 an explicit when (the user asks directly, or after a tool returned AUTH_REQUIRED and the user wants a re-check) and an explicit when-not (no preflight before protected tools), naming the alternatives to call instead. The reasoning behind the exclusion — a 401 that gets swallowed and prevents the MCP client from triggering OAuth — is also 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?

The description adds substantial behavioral context beyond annotations: confirm=true completes the sale immediately, money leaves the caller's XP USDC balance, and the seller is committed. It also discloses authentication requirements and clarifies that the x402 rail applies only to buy_tickets, not fan listings. This is consistent with destructiveHint=true and readOnlyHint=false.

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

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

The description is front-loaded with the core action and scope, then moves through alternatives, two-phase behavior, financial consequences, payment rail, and auth. Every sentence contributes operational guidance for a high-stakes purchase 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 destructive nature of the operation, the existing output schema, and rich annotations, the description covers the key missing context: preview vs. purchase semantics, authentication, payment source, price-change protection, and the alternative for listings without an ask. Nothing critical for correct invocation 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 coverage is 100%, so the baseline is 3, but the description adds workflow meaning: confirm=false previews the total for read-back, confirm=true executes the purchase, and ask_per_ticket_usd must match the previewed price or the purchase is refused. This goes beyond the schema's field-level descriptions by explaining the safety contract between preview and purchase.

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 ('buy a fan listing outright at the seller's published asking price') and clearly distinguishes this from negotiation and from make_offer_on_listing. An agent can identify the exact purchase action without opening the schema.

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

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

It explicitly says when to use this tool: an authenticated buyer wants to purchase at the ask rather than negotiate. It also states when not to use it by routing listings without an asking price to make_offer_on_listing, and explains the two-phase preview/buy workflow.

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 write/destructive/openWorld flags; the description adds substantial context beyond them — required scopes (write:tickets, plus read:account for the balance preflight), the two-phase preview/confirm contract, what the preview returns (payment_link, checkout_session_id), what confirm returns (stripe_payment_intent), and the explicit need for user approval. It is consistent with destructiveHint=true by gating execution behind explicit approval.

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 trigger and default rail, then progressively discloses the alternative rails, so the most important content comes first. It is dense and heavily parenthetical for a single paragraph, but the length is defensible given four payment rails and a multi-step confirm 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?

For a destructive, nine-parameter purchase tool with four payment modes, the description covers permissions, the preview/confirm state machine, per-rail return values, and client capability constraints. An output schema exists, so return-value detail is a bonus rather than a gap, and nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already explains each parameter well. The description still adds meaning the schema lacks: rail-selection heuristics, the mpp credential fallback via params._meta when a client cannot send _meta, and the ordering relationship between the preview's checkout_session_id and the confirm call.

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 — buying tickets to an event on the XP marketplace connected order book — and frames it as a purchase flow, which is far more than a restatement of the name. However, it never distinguishes itself from the closely named sibling buy_listing_now, leaving the agent to infer that this tool operates on ticket groups (uvid) rather than listings.

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

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

Explicitly states when to use it ('when the user wants tickets to an event'), which rail to pick by default and when to switch ('use stripe_link unless the user asks for another'), and gives a per-rail condition for the non-default options including a caution that x402 should only be used by callers that can sign Solana payloads. The preview-then-confirm sequencing is spelled out as a procedure.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantial context beyond them: open offers are rejected and buyers notified, the action cannot be undone, relisting requires create_listing, and it works only on the caller's own authenticated listing. This is rich behavioral disclosure well past the annotation floor.

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 primary use case and trigger phrases, then layers constraints and side effects in descending priority. Despite its length, nearly every clause (offer rejection, irreversibility, accepted-offer exclusion, auth scope) carries operational weight.

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 needn't be described, and the description fully covers prerequisites, side effects, irreversibility, and the preview pattern. For a destructive two-param tool this is complete.

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

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

Schema coverage is already 100%, so the schema documents both parameters; the description still reinforces the confirm=false/true preview-vs-commit semantics and advises saying so before committing, adding decision-context beyond 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?

Specific verb+resource: closes a seller's own listing so buyers cannot make an offer. It names the exact trigger phrases and clearly distinguishes this from sibling actions like cancel_my_offer by scoping to the caller's listing. An agent can identify the operation 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 (seller removing own listing), colloquial triggers, and a clear when-not: it cannot be used once an offer is accepted, since that is an agreed sale handled by support. The two-phase confirm flow is also spelled out as a usage pattern.

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

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

Beyond the destructiveHint annotation, it discloses two-phase write behavior, the need for auth and write:bids scope, the fact that only confirm=True returns success=true, and that the server can resolve the buyer swap id. These are material mutation and authorization details an agent needs before acting.

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 two-phase workflow and uses each later sentence to cover prerequisites, identifier sourcing, exclusions, and alternatives. It is slightly repetitive in saying both 'connected resale order book' and 'live offer book', but overall it is appropriately sized for a destructive transaction tool.

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

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

For a destructive mutation with an output schema and full annotation coverage, the description is complete enough to call correctly. It covers prerequisites, confirmation sequencing, identifier resolution, success conditions, exclusions, and alternatives.

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 parameter meanings are already well documented. The description still adds useful context by naming make_offer_on_listing as the source of bid_uuid and by reinforcing the confirm=False versus confirm=True semantics with the success condition.

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: rescind an outstanding offer on an XP marketplace listing. It distinguishes this mutation tool from discovery/browse tools and from buy-now ticket purchases, and it names the related make_offer_on_listing tool for the identifier source.

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 gives when to use the tool and how to sequence calls: confirm=False first for preview, confirm=True only after explicit user approval. It also states exclusions and alternatives for browse/discovery and standard buy-now purchases.

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?

Substantively it is rich: it discloses the required X-XP-Correlation-Id header, that a missing header yields a structured error rather than a failure, that the tool never raises 401, that found:false is a normal empty result, and the exact failure payloads. However, it labels the tool 'open-world (no bearer/OAuth needed)' while the annotations declare openWorldHint=false, which is a direct clash on a declared trait and muddies the auth/trust model the agent is supposed to rely on.

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

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

It is front-loaded and well sectioned (IDENTITY, ARGS, POLL LOOP, RESULT SCHEMA, BUCKETS, EVENT VOCABULARY, FAILURES), so it is easy to scan. But it reproduces an entire result schema verbatim even though an output schema exists, which is bulk that the structured field could carry. The BUCKETS and EVENT VOCABULARY blocks do earn their place because they encode enumeration semantics an agent cannot infer.

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 polling tool with a cursor protocol, the description covers everything an agent needs: header-based identity, cursor round-tripping, truncation paging, bucket meanings, event vocabulary, and the full error set. Nothing material about correct invocation or result interpretation is left to 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 coverage is 100% and the schema already documents `since` as the previous call's cursor with a >=0 constraint. The description still adds real meaning beyond that: where the cursor comes from, that omitting it fetches the feed from the beginning, and that a negative value returns {"error": "invalid_since"}. This is genuine added semantics over a well-documented single parameter.

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

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

The description opens with a specific verb and resource: 'Poll the current status and action feed for the listing tied to this call's correlation id.' The correlation-id identity model implicitly separates it from sibling tools such as get_my_listing_status or get_order_status, which presumably key off auth identity. It never names an alternative explicitly, which keeps it 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 POLL LOOP section gives clear operational context: omit `since` on the first call, store `cursor` per correlation id, send it back, and render only new `actions` rather than diffing `listing` yourself. It also explains the truncation retry path. What is missing is any statement of when to prefer this tool over sibling status tools (get_my_listing_status, get_order_status), so it stops short of explicit alternatives/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 flag a non-readonly, destructive write; the description adds the traits annotations cannot express: no tickets move at listing time (transfer follows an accepted offer), new listings are reviewed, and the result's listing_state may be live/in_review/not_accepted with an explicit warning never to claim the seats are for sale unless state is live. It also notes the auth requirement.

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 trigger phrase, then layers call mechanics, review behavior, and result interpretation in a logical order with no filler sentences. It is dense and long-ish for a single tool, but nearly every clause carries operational information the agent needs.

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

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

Despite 12 parameters and a mutation with a review gate, the description covers the workflow prerequisites, the two-phase confirmation, the auth requirement, and the interpretation of listing_state — the risky ambiguity for this tool. Output schema handling of return shape is appropriately left to the schema.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns an extra point by elevating is_ada, is_obstructed_view, and is_sro into a required seller-interview workflow ("never assumed") and by explaining what confirm=false previews actually surfaces (section, row, seats, the three flags). Pricing and seating parameters 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?

"Use when the user wants to sell tickets they hold on the XP marketplace" states a specific verb, resource, and audience, then reinforces it with three natural-language triggers. It explicitly separates the tool's role from accept_offer/reject_offer (seller responding to offers) and from transfer, so an agent can place it precisely among siblings.

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

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

Gives concrete when-to-use phrasing ("sell my two seats for Friday") and an implicit when-not: this is listing creation, not offer handling or ticket transfer. It also prescribes a prerequisite conversation (ask about ADA/obstructed/SRO) and a two-phase call pattern before creation.

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=false, destructiveHint=true, openWorldHint=false; the description goes well beyond by disclosing the two-phase confirm preview flow, that fills take whole lots with no stranded remainder, that whole-dollar pricing is enforced, that auth is required, and that the offer rests on a live offer book that self-fills. This is exactly the extra behavioral context the annotations cannot convey.

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

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

Purpose and the sibling contrast are front-loaded, and most sentences carry decision-relevant content. It is long and leans on parenthetical asides and meta-instructions ('that is the term to use when speaking to the user'), which slightly dilute density, but nothing is truly 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, full schema description coverage, and annotations covering the safety profile, the description supplies everything else an agent needs: auth requirement, two-phase calling convention, pricing granularity, fill behavior, and alternative-tool routing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: the two-phase confirm=false/true lifecycle, the whole-dollar constraint rationale ('XP refuses cents so every fill passes per-ticket validation'), and the whole-lot fill semantics that qualify quantity. Some of this overlaps the schema ('Cents are not accepted'), keeping it below a 5.

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

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

The description states a specific verb and resource ('Creates a STANDING OFFER'), defines the term explicitly, and distinguishes it from the closely related make_offer_on_listing and buy_listing_now by explaining the fill/wait mechanic. An agent can identify this tool without inspecting 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 concrete when-to-use triggers with example utterances ('offer 80 a seat for any of these nights'), names the alternatives (make_offer_on_listing, list_open_listings, get_market_read), and explicitly clarifies that both paths are valid to forestall misuse. Exclusions and pre-checks are all present.

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 present but sparse (readOnlyHint=false, which the description does not clarify or contradict), the description adds real behavioral context: the prioritization algorithm, the deduplication rule ('Skip anything already known'), and the exact-label contract for returned metro names. It stops short of explaining why this read-like 'Get' is not marked read-only (possibly agent_name tracking), leaving a small ambiguity.

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 summary line followed by the ordering rule and the downstream-call instruction, with no filler. The only minor cost is unexplained jargon ('XP') in the first sentence.

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

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

An output schema exists, so return values need not be described; the description nonetheless covers ordering, deduplication, and downstream usage. What is missing is edge-case behavior (e.g., how `near` is matched if the city is unknown or ambiguous) and any note about why the tool is flagged non-read-only.

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 it by explaining the consequence of `near` in the ordering and by defining `geo_metro` as a verbatim label drawn from this output. It does not mention `limit` or how `agent_name` affects which plan is returned.

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 line states a concrete resource and its content: an ordered list of US metros to search for new sources plus the sources already held. It is immediately distinguishable from siblings like add_my_sources or search_market, which act on sources or listings rather than producing a prioritized discovery plan.

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

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

It gives explicit ordering rules ('near' first, then metros with no sources, then the rest), says to skip known sources, and directly instructs how to feed results forward: 'Set geo_metro to the metro label exactly as given here when you call add_my_sources or submit_discovered_sources.' That is concrete when-to-use and how-to-chain guidance naming the two downstream 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real context beyond that: the data source ('Pulls from the XP marketplace catalog') and an operational instruction to cache results per conversation rather than re-calling for the same event_id. It doesn't cover failure behavior for an unknown event_id, which is the only notable gap.

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

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

Three sentences, front-loaded with the usage trigger, then the data source, then the caching rule, then the exclusion. Every sentence contributes a distinct piece of information with no repetition of the schema or annotations.

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 document return values, and it correctly focuses on selection guidance, source, and caching. For a simple one-parameter read tool this is nearly complete; only error/edge behavior (e.g. invalid event_id) is unaddressed.

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

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

There is a single required parameter with 100% schema description coverage, including where the ID comes from ('search_events or a previous user selection') and a format example. The description adds no further parameter semantics, so the schema does the heavy lifting and the baseline of 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 names a specific verb and resource ('full event card' for an event ID) and enumerates what the card contains: venue, performers, fee-inclusive price preview, images. It also explicitly rules out the sibling use case, so an agent can distinguish it from get_ticket_listings and get_venue_details 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 states the triggering precondition ('event ID is in hand'), the intent ('wants the full event card before browsing tickets'), an explicit exclusion ('Do not use to list ticket inventory'), and names the correct alternative ('`get_ticket_listings` is the right tool for seat-level data'). Nothing is left to inference.

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

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

Annotations give only readOnlyHint=false / destructiveHint=false / openWorldHint=false; the description adds the traits that actually matter here -- the job is a time-limited lease ("expires after expires_in_seconds"), sources are excluded while "in use," allocation is least-recently-searched-first, and an empty result is normal but still must be submitted. That explains why readOnlyHint is false despite the 'get' name.

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

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

Front-loaded with the purpose before the procedural detail, and nearly every sentence carries an actionable constraint. It runs long with stacked parentheticals ("even if you found nothing (send an empty list)"), but no paragraph 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 leased-assignment tool with an output schema, the description covers the happy path, the empty/no-source path with its exact sentinel response, the failure path, expiry, and a pointer to skill://instructions/listener-node for deeper detail. An agent could act correctly without opening anything else.

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 behavioral meaning for can_read ("Only sources matching can_read are handed out; the response echoes the stored set"), which is more than the schema's declaration/persistence note. agent_name and preferred_platforms get no added context 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?

Starts with a specific verb and resource: "Get the next listening job: one group or search to read, with the rules for reading it." This is unmistakably distinct from siblings like submit_seller_leads and search_events, which are named as downstream steps rather than alternatives.

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

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

Explicitly sequences the whole workflow: read the source read-only, honor max_post_age_hours and max_posts_to_scan, call search_events per post, then submit once via submit_seller_leads. It also names the fallback ("could_not_read true") and the stop condition ("stop rather than looping"), so no routing decision is left to inference.

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

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

Annotations only declare read safety; the description adds substantial non-obvious behavior: floor-first row ordering, the dominance rule ('a row shown only when it is cheaper than every row in front of it'), fee-inclusive pricing at party size, and that fan listings open to offers are included. Critically it discloses a data gap — no specific cheapest fan ask is surfaced — preventing the agent from fabricating one.

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 usage trigger and no filler sentences; every clause carries either output semantics or a reporting constraint. The middle sentence is a long chained clause enumerating the matrix structure, which costs some readability but the content justifies the 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?

For a three-parameter read tool with an output schema and read-only annotations, the description covers the remaining burden: what the matrix contains, how rows are ordered and filtered, and how the agent should present results. The 'do not describe the market with averages, medians, or maximum asks' directive closes the main misuse risk.

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 by explaining that prices are 'fee-inclusive per ticket at the party size,' clarifying quantity's effect on the returned numbers rather than just filtering. Sections are only indirectly referenced via 'per section's rows,' so it stops short of full extension.

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 ('Returns XP's ticket price matrix from the connected order book') and immediately distinguishes itself from row-browsing siblings with 'not just browse rows.' The detailed content of the matrix (per seat level, floor first, rows front to back) makes the tool's output shape unmistakable relative to search_market or get_ticket_listings.

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

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

Gives a clear triggering condition ('when the user wants to understand what an event is trading at') and an explicit negative condition ('not just browse rows'), which implicitly routes the agent away from listing-browse tools. It never names a sibling tool outright, so the alternative is inferable rather than explicit.

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

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

Annotations only cover the safety profile (readOnly, non-destructive), but the description adds substantial behavior: bids are classified open/completed via the admin outcome engine, rejected/lapsed/refunded bids are hidden, pagination defaults and limits, and OAuth is required. That filtering and visibility detail is exactly what annotations cannot convey.

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

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

Front-loaded with the when-to-use trigger, followed by visibility rules and pagination facts. Dense but each clause carries operational information; only the pagination restatement is mildly redundant with the 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?

With an output schema present, return values need not be re-explained, yet the description still clarifies that pagination.total counts only visible bids and how to phrase has_more results. Nothing needed to call this tool correctly is missing.

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

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

Schema description coverage is 100%, so limit and offset are already documented in the schema; the description largely restates the 1-200 range, 25 default, and offset paging. It adds no new syntax or edge-case semantics beyond what the schema provides.

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 (see) and resource (bids placed by the authenticated user) with concrete example utterances ('show my bids', 'did any of my bids settle?'). It is clearly distinguishable from siblings like get_my_orders and list_my_standing_bids.

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

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

Provides clear triggering context via example phrasings and scopes it to the authenticated user's own bids. It does not explicitly contrast against near-neighbors such as get_my_orders or list_my_standing_bids, so an agent must infer the boundary.

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

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

Annotations declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is already covered. The description adds valuable context beyond annotations: it clarifies that nothing said in the current conversation is stored and that a new budget only persists as a resting commitment (referencing create_standing_bid). It also explains the intended use of notes ('shape what you say, never read them back verbatim'). This is rich for a read tool, though it could mention response format or caching.

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

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

The description is front-loaded with the primary purpose and timing. It is a bit long (four sentences) and includes some verbose phrasing like 'e.g. re-asking a budget right before you help them make an offer on the XP marketplace,' but every sentence still earns its place by conveying a distinct usage rule or behavioral caveat.

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 retrieval tool with one required parameter, full schema coverage, annotations covering safety, and an output schema (so return values need not be described), the description is complete. It covers timing, purpose, behavioral caveats, and cross-references the sibling tool create_standing_bid. Nothing critical is missing 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% – the schema already fully documents event_ids ('Event IDs the user has settled on. Usually one.'). The description does not add any parameter syntax, format, or edge-case details beyond what the schema provides. 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?

Clearly states what is retrieved (budget per ticket, quantity, date flexibility, notes) and its temporal position ('once the user has settled on an event, before quoting prices'). The phrase 'what they already told XP' is slightly colloquial but still defines the resource as stored user-provided context. It doesn't explicitly distinguish itself from get_user_account, but the scope is specific enough to be useful.

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 to use it ('once the user has settled on an event, before quoting prices') and why ('stops you asking twice'). It also gives a constraint ('use saved notes to shape what you say, never read them back verbatim'). However, it does not name alternative sibling tools for retrieving user data (e.g., get_user_account) or say when NOT to use it, so it falls short of a 5.

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

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

Annotations already declare this a safe read, but the description adds material context beyond them: auth plus the read:bids scope requirement, the critical caveat 'trust visible_to_buyers, not the state', the dollars interpretation of amount_usd, and an explicit precedence rule that sold-listing transfer obligations must be surfaced first. It also maps is_seller offer actions to accept_offer/reject_offer, which pre-wires the follow-up call.

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

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

Almost every sentence carries operational value, and the fragmented phrasing ('From XP's connected resale order book') is minor. The structural weakness is front-loading a rare edge case (sold listing awaiting ticket transfer) ahead of the primary polling use, which buries the headline purpose.

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 clarifies the few return fields an agent would misread (amount_usd currency, visible_to_buyers as ground truth, per-offer actions). Auth requirements, seller vs buyer scope, and the post-create_listing verification role are all covered, leaving no gap 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?

Only one parameter and schema coverage is 100%, so the schema already documents identifier, including its source tools. The description doesn't add format, validation, or lookup-failure semantics beyond that. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('poll their listing on XP') and enumerates what it returns: open bids, state, seats, plus the seller's view of the live offer book. It explicitly distinguishes itself from the buyer-side sibling ('A buyer browsing open listings uses list_open_listings') and from list_my_listings, so an agent can route correctly 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 concrete when-to-use conditions: polling before deciding to accept/reject an offer, and confirming what XP stored after create_listing, complete with a worked example query. It also names the exclusion (buyer browsing) and the alternative sibling, which is the full when/when-not/alternative triad.

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 the safety profile (readOnlyHint=true, destructiveHint=false), and the description adds real context on top: auth requirement, newest-first ordering, dollar-denominated money, and the fields surfaced. It does not discuss pagination behavior, though ordering is 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 purpose and trigger phrases before the routing exclusions. The example queries add genuine matching value rather than filler, though the definition is on the longer side.

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 list tool with a rich output schema and full annotation coverage, this covers everything an agent needs: what it returns, ordering, auth, and which siblings to prefer. Nothing material is missing.

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

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

Schema description coverage is 100% (the single 'limit' param documents range 1-50 and default 20), so the schema carries the full burden. The description adds nothing about the limit parameter, which is the correct baseline of 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?

States a specific verb (Show) and resource (the authenticated user's own orders on the XP marketplace) plus the scope 'where each one stands'. It is clearly distinguishable from siblings like get_my_tickets and list_my_listings.

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 trigger phrases ('where is my order', 'did my tickets go through', 'what did I buy for Saturday', 'when do my tickets arrive') and three explicit when-not routes naming the correct alternatives (get_my_tickets, list_my_listings, get_my_bids).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond them: 'Requires auth' and the important scoping caveat that only delivered tickets surface while pending swaps live in list_my_listings. It does not describe rate limits or pagination behavior, so it falls short of a 5.

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

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

Front-loaded with the core purpose before the routing and exclusion details, and every sentence carries a distinct fact (scope, triggers, alternative, auth, exclusion). It is somewhat dense for a two-parameter list tool but not padded.

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

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

An output schema exists, so return values need not be explained. Auth requirement, scope boundaries, the sibling alternative, and the exclusion are all present — 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% and both parameters (limit, offset) are fully documented in the schema with defaults and ranges. The description adds no syntax or semantic detail 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+resource+scope: 'Show the authenticated user the tickets currently delivered to their XP marketplace account.' It explicitly distinguishes itself from list_my_listings (pending swaps/seller-side) and get_my_orders (past orders), so an agent can route correctly 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 concrete trigger phrases ('my tickets', 'pull up my seats for tonight'), names the sibling alternative for the adjacent case, and includes an explicit exclusion: 'Do not use to list past orders or browse the marketplace.' Both when-to-use and when-not-to-use are 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?

Annotations already declare readOnlyHint/destructiveHint, but the description adds meaningful context: requires auth and read:account scope, and explicitly does not expose the raw bearer token. It also names the wallet_connected flag, which is behavioral detail 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?

Front-loads the 'Use when...' trigger, then the return contract, then auth/privacy notes. Dense but each clause earns its place; only mildly long.

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

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

An output schema exists so return values need not be re-explained, yet the description still summarizes the key shape and covers auth scope and token-safety. Nothing needed to invoke it correctly is missing.

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

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

There are 0 parameters, so the baseline is 4. There is nothing for the description to clarify, and it appropriately says nothing about inputs.

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

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

States a precise verb+resource (retrieve the authenticated user's Privy embedded-wallet address and USDC balance) and names the exact return fields. It is clearly distinguishable from siblings like get_user_account or get_my_context.

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

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

Gives concrete triggering user utterances ('what's my wallet for tickets to tonight?') and context ('Used to fund offers on the live offer book'). It does not explicitly name an alternative tool or say when NOT to use it, so it stops short of a 5.

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

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

Annotations already establish read-only, non-destructive, closed-world behavior, and the description adds auth requirements ('Requires auth and read:bids scope') plus the live nature of the data ('one row from the live offer book'). It does not describe error behavior for a stale or missing identifier, which keeps it from a 5.

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

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

Content is front-loaded with the resale order book context, then the usage condition, then alternatives. Slightly verbose with multiple parenthetical tool names, but each clause carries routing or scope information.

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

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

With an output schema, full parameter schema coverage, and clear annotations, the description fills the remaining gaps: when to use it, which siblings to prefer instead, auth/scope requirements, and that it returns a single row of live offer data. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and the parameter's description already says the identifier is a public listing ID from list_open_listings. The prose adds only that the identifier must already be in hand; it does not expand on format or provenance beyond the schema.

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

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

States a specific verb and resource: fetch the full record for one open listing by identifier. It explicitly distinguishes itself from list_open_listings (the list variant) and from search_events/get_ticket_listings (the plain buy-now path), so an agent can tell exactly which tool this is.

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

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

Gives a precise trigger ('when a listing identifier is in hand' and before make_offer_on_listing or buy_listing_now) and a precise exclusion ('for a plain buy-now at the asking price without an offer, use search_events and get_ticket_listings instead'). Alternative tools are named explicitly.

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 the safety profile (readOnly, non-destructive, closed-world), so the bar is lower. The description adds genuine context beyond annotations: it requires auth, only the caller's own orders are visible (a real access constraint), and it enumerates what the response contains including currency units.

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

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

Front-loads purpose, then usage triggers, then return contents, then constraints and the alternative. Every sentence is functional with no filler, despite being fairly information-dense.

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

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

An output schema exists so return-value documentation isn't required, yet the description still summarizes the returned fields usefully. Auth, visibility scope, and currency are all covered, leaving nothing an agent needs missing.

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

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

Schema description coverage is 100%, so the schema already documents the single required order_uuid. The description restates its provenance from buy_tickets and get_my_orders, which the schema description also provides, so it adds little beyond the baseline.

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

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

States a specific verb (Get), resource (status of an order), and scope (the authenticated user's own orders on the XP marketplace), keyed by order_uuid. It also distinguishes itself from the sibling get_my_orders, which handles the multi-order list case.

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 triggers ('right after a purchase', user asking about a specific order) plus concrete example phrasings. It also names the alternative to reach for when no order_uuid is available ('use get_my_orders for the recent list').

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 a safe read (readOnlyHint, destructiveHint=false, openWorldHint=false), and the description adds meaningful semantics beyond that: fee-inclusive per-ticket dollars, one point per day, oldest first, and the crucial caveat that an empty history is a legitimate and common result because XP only records tracking events. Minor deduction because some return-shape detail overlaps with the existing output schema.

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

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

Front-loads the usage triggers, then the return shape, then the disambiguation and the empty-history caveat. Four sentences, each carrying distinct information with no repetition of schema or annotations.

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 read-only two-parameter tool with an output schema and full annotation coverage, the description supplies exactly the missing pieces: intent triggers, price semantics (asking vs sold), and the empty-vs-flat distinction that an agent would otherwise misread as an error.

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%, with both `days` (1-90, default 30) and `event_id` (from search_market or search_events) fully documented in the schema. The description adds no parameter-level detail such as interaction between the days window and the empty-history behavior, 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 (retrieves daily closing get-in price history for an event) and defines the granularity and ordering: one point per day, oldest first. It also draws an explicit boundary against the sibling get_recent_sales by contrasting asking price over time with actual sold prices.

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?

Opens with concrete user-intent triggers ('are prices rising or falling', 'buy now or wait', 'what has this event been doing lately'), and names the alternative tool get_recent_sales with an explicit warning not to conflate the two. 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?

Annotations already declare this a safe read, so the description adds genuine behavioural context: an empty result is a meaningful answer (no verified transfers in the window), the data is completed deals rather than asks, and results include time-since-clear. The caution against generalising from a single sale warns about interpretation risk that no structured 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 trigger condition is front-loaded and each sentence carries a distinct payload: trigger, return contents, empty-result meaning, decision use, interpretation caveat. Slightly long for a one-parameter read tool, with the final caveat bordering on advisory padding, but nothing is redundant.

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

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

For a single-required-parameter read tool with annotations and an output schema, the description covers the only things structure cannot: when to reach for it, that empty means genuinely no trades, and how much to read into a thin result. Nothing an agent needs to call or interpret it is missing.

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

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

Schema coverage is 100% and the single event_id parameter is fully documented there, including its source (search_market or search_events). The description adds only indirect meaning ("on an event") and no format or scoping detail 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 — recent completed deals from the XP marketplace with per-ticket price and time since clearing — which clearly separates it from listing/offer tools. It does not name a sibling explicitly (e.g. get_price_history, get_ticket_listings), so differentiation is inferred 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?

"Use when the user asks what tickets actually sold for" is an explicit trigger, and "before claiming nothing has traded" plus "before deciding whether to make an offer or wait" give clear decision contexts. It never names an alternative tool to use instead, so the when-not/alternative half of the guidance 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 cover the read-only safety profile; the description adds substantive behavior beyond that: the return type is an image, chart coverage is not universal, missing-chart handling is prescribed ('say so plainly'), and auth is stated as unnecessary. The explicit prohibition against describing it as a seat-view photo heads off a known mislabeling failure.

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 use case and the return type before the caveats, and every sentence carries operational content. Slightly long, with the layout-vs-photo distinction restated twice, though that repetition targets a high-risk error.

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?

Output schema exists, so return values need no prose, and the description still covers the image payload, the missing-chart edge case, the fallback path via get_ticket_listings, and auth requirements. An agent has everything needed to call it and interpret an empty 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?

Only one parameter, and the schema already documents it at 100% coverage including where the event_id comes from (search_market, search_events, get_event_details). The description adds no further parameter semantics, 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 ('Returns the venue seating chart as an image') and immediately bounds it against the most likely confusion: it is a layout, not a seat-view photo. It is clearly separable from siblings like get_venue_details and get_ticket_listings.

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

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

Gives concrete triggering utterances ('where is 104', 'show me the map', 'is that behind the stage') plus an explicit when-not (not a photograph of the view) and names get_ticket_listings as the fallback source of section/row detail. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that: it returns offers at any status including filled and rescinded, includes the fills taken, and requires auth. It doesn't add anything about pagination or result size, but the status-spanning behavior is a real 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?

Two sentences, front-loaded with the trigger and example queries, then the differentiating capability and the auth requirement. 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 an output schema covering return values, a one-param schema at full coverage, and read-only annotations, the description supplies everything else an agent needs: when to call it, what statuses it spans, and that auth is required.

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

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

Schema coverage is 100% for the single standing_bid_id parameter, and the schema itself documents where the id comes from (list_my_standing_bids or create_standing_bid). The description adds no syntax or format detail beyond that, so the baseline of 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 ('get one specific standing offer') and explicitly scopes it relative to the sibling list tool, noting it covers filled and rescinded offers that list_my_standing_bids omits. An agent can pick this over the sibling 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?

Opens with an explicit trigger ('Use when the user asks about one specific standing offer') and gives concrete example questions ('did that offer get my tickets'), then names the alternative and the condition that selects this tool over it.

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

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

Annotations already cover the read-only/non-destructive profile, and the description adds substantial non-obvious behavior: prices are in dollars with a per-row `per_ticket_usd` field, and three named error codes are decoded into actions (NO_INVENTORY = do not retry, NO_MATCHING_TICKETS = widen filters, EVENT_NOT_FOUND = re-resolve the event). This is exactly the retry/routing context an agent cannot infer from structured fields.

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

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

Front-loaded with the trigger condition, then behavior, then error semantics — a sensible priority order with no filler. It is on the long side and restates the dollar/pricing point that the schema also carries, which keeps it just below a 5.

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

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

For a 17-parameter read tool with full schema coverage, an output schema, and annotations, the description supplies the remaining pieces an agent needs: prerequisite ordering, price units, and error-driven recovery paths. Nothing essential to 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?

With 100% schema coverage the baseline is 3, but the description adds interpretive value: it clarifies that price filters and results are dollar-denominated all-in prices and that 'none fit the filters' should be handled by widening or dropping them. It does not cover other notable params (quantity default, sections vs section_ids aliasing, deprecated cents fields), so it falls short of a 5.

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

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

States a specific verb+resource ('see ticket options and fee-inclusive prices'), names the prerequisite tool (`search_events`), and characterizes the data source as 'the live offer book of resale inventory'. This clearly separates it from `search_market`, `get_seat_map`, and `get_event_details` in the sibling list.

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 trigger ('after search_events', example user phrasings 'cheap seats', 'parking for the game') and an explicit exclusion ('Do not use before an event has been resolved — call search_events or get_event_details first'). It even routes follow-up decisions by error code, which is more than most definitions offer.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so 'Read-only' partly repeats structured data. However, the description adds the auth requirement, which annotations do not convey, and clarifies the aggregate nature of the payload (account card combining profile, wallet, orders, referral stats).

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 resource and its payload, then usage examples, then the exclusion. The six quoted example phrasings are somewhat repetitive, but each maps to a distinct sub-query and remains short overall.

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

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

With an output schema present, the description need not explain return structure, and it still notes the payload mirrors the account page. It covers scope, auth, and the sibling boundary — nothing an agent needs to call 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?

The tool takes zero parameters, so the baseline of 4 applies — there is nothing for the description to disambiguate at the parameter level.

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 (pull) plus resource (authenticated user's XP account card), and it enumerates the concrete contents — profile, wallet, email, name, order history, referral stats. It differentiates from the nearby get_my_orders and get_my_referral_kickbacks siblings by naming one alternative explicitly.

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

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

Gives both when-to-use (user asks 'my account', 'my orders', 'my referral link') and an explicit when-not-to-use with the alternative named: tickets delivered to the account should use get_my_tickets instead. An agent can route without inference.

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

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

Annotations already declare a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds real value by disclosing that results are merged from three sources including a live order book, and that the feed is meant to tee up a follow-on `get_ticket_listings` call. It stops short of covering latency, pricing freshness, or how partial/empty venue data is handled.

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

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

Purpose is front-loaded in the first clause, followed by usage triggers, expected return, and exclusion — a sensible order. It runs slightly long, with the quoted example phrasings and the return-value sentence partially overlapping, but nothing is truly wasteful.

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 covers return shape and annotations cover safety, so the description only needs selection guidance and scope — both are present, including the boundary against the sibling ticketing 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?

Only one parameter with 100% schema description coverage, which already says it is the 'Venue identifier from search_venues.' The description reinforces the search_venues provenance but adds no format or edge-case guidance beyond the schema, 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?

States a specific verb and composite resource: full venue info from XP, the upcoming-events calendar, and live resale pricing from the connected order book. It clearly separates itself from get_ticket_listings and get_event_details, so an agent can pick it without opening a schema.

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

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

Gives the preceding step (after `search_venues`), concrete trigger phrasings ('what's coming up at the venue', 'shows at the venue this month'), and an explicit exclusion: do not use for a specific event's seat-level inventory — use `get_ticket_listings` 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?

Beyond the annotations (readOnly/destructive=false/closed-world), it discloses meaningful behavior: muting is per-user and never touches the listing itself, it hides the listing only on xp.tickets, and sibling read tools do NOT filter muted listings. It also notes auth is required.

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 trigger condition, then behavior, then the operational warning. Dense but every sentence carries new information; only minor trimming 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?

An output schema exists so return values need not be detailed, and the description still summarizes them. For a zero-arg, annotated, output-schema-backed tool, nothing an agent needs to invoke it correctly is missing.

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

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

Zero parameters, so there is nothing for the description to clarify and the baseline is 4. The description correctly adds no filler about inputs.

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

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

States a specific verb and resource ('Returns the listing identifiers this user has muted') and names the sibling tools it relates to (list_open_listings, get_market_read), so an agent can distinguish it from the many list_* siblings without opening a schema.

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

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

Explicit when-to-use: when the user asks what they have hidden/muted, and crucially before muting (to avoid duplicate-mute claims). It also warns to read this list before showing listings for offers, naming the exact alternative tools that fail to filter muted items.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds genuinely new behavioral context: the read:account scope requirement, default/limit pagination bounds, and the edge case that some accounts follow thousands of performers so pagination.has_more should be surfaced to users.

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 trigger condition, then auth/scope, then sibling pairing, then pagination behavior. Every sentence carries a distinct operational instruction 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?

Output schema is present so return values need no explanation, yet the description still references pagination.has_more to tell the agent how to interpret and phrase results. Nothing needed to call or report this tool correctly is missing.

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

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

Schema coverage is 100%, so both limit and offset are already documented in the schema. The description restates the same 25/200/offset facts without adding syntax or constraint detail beyond what the schema provides, 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 ('list the performers they've favorited') plus the marketplace scope, which cleanly separates it from siblings like list_my_listings, list_my_standing_bids, and search_performers.

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?

Opens with 'Use when an authenticated user wants...' and supplies concrete trigger utterances, the auth/read:account prerequisite, and an explicit pairing with search_events for the follow-on ticket lookup. An agent knows exactly when to pick this over search_performers.

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 this as a safe, read-only, closed-world operation, so the description appropriately focuses on non-annotation traits. It adds the auth and read:bids scope requirement, explains that a 'large book' returns one page per lifecycle category with per-category pagination totals, and warns never to present a partial page as the whole set.

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 pagination behavior and then moves to usage and alternatives, with no wasted sections. The 'large book' metaphor and some dense phrasing make it slightly less crisp than ideal, but every sentence carries actionable information.

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

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

Given that an output schema exists and annotations cover safety, the description is complete enough to call correctly: it covers ownership scope, auth, pagination behavior, category bucketing, and the correct sibling alternatives. Nothing material for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful operational semantics beyond the schema by explaining how offset and state_category are intended to be used for paging or narrowing results, though it does not restate the per-category limit semantics.

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

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

The description states a specific verb and resource: list an authenticated seller's own XP marketplace listings, bucketed by lifecycle category. It explicitly distinguishes this from buyer-facing siblings like list_open_listings, search_events, and get_ticket_listings, so an agent can choose correctly without opening another 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 concrete when-to-use examples ('show my tickets I'm selling', 'what's open in my seller queue') and names the alternatives for buyer browsing and buy-now flows. It also tells the agent what to do when has_more is set: disclose the partial page and either page with offset or narrow with state_category.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value beyond that: it discloses the auth requirement, that the result set is filtered to live offers, and where the excluded states (filled, rescinded) have gone — genuinely useful behavioral context for interpreting the output.

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 tight sentences, front-loaded with the usage trigger, followed by the concept definition and the live-only scoping rule. No filler and no restatement of the tool name; each sentence carries a distinct fact.

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

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

An output schema exists, so return-value explanation is unnecessary and the description rightly omits it. Combined with the auth note, the live-only scoping, and the sibling routing for excluded offers, an agent has everything needed to call this correctly on the first attempt.

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 zero parameters, the baseline is 4. There is nothing further to document, and the description correctly does not invent parameter guidance; it instead spends its words on scope and routing, which is the right allocation for a no-arg 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 states a specific resource (standing offers on the XP marketplace) and explains the concept in plain terms: 'A standing offer buys at the user's price whenever a matching fan listing appears.' It explicitly scopes the listing to live offers only and names the sibling that retrieves historical ones, so an agent can distinguish it from get_standing_bid and get_my_tickets without opening a schema.

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

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

It gives explicit triggers ('when the user asks what offers they have resting... or before they make an offer so you do not stack a duplicate') and names the alternatives for the non-live cases: filled offers are reachable via get_my_tickets and rescinded ones via get_standing_bid. When-to-use, when-not-to-use, and alternatives are all present.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: auth plus the read:bids scope requirement, and the fact that results flow into an offer-negotiation workflow. It says nothing about result volume or truncation behavior, but the output schema covers the return shape.

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

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

Purpose is front-loaded, then usage examples, downstream tools, filters, auth, and the negative routing — roughly the right order with no filler. It is dense (five clauses in one block) but 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 10 optional parameters, full schema coverage, an output schema and read-only annotations, the description supplies what structure cannot: auth scope, workflow position, and sibling routing. The only gaps are edge behavior around limits and the deprecated amount fields, which are minor given the schema carries them.

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 all 10 parameters are documented structurally, which sets the baseline at 3. The description only restates the filterable dimensions at a high level ('event, performer, and amount') and adds no syntax or format detail. It also doesn't clarify the odd mismatch where the schema's `days` and `limit` descriptions talk about offers rather than listings, nor does it mention the deprecated min_amount/max_amount fields — though the schema itself flags both.

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 ('list resale listings from XP's connected order book') and immediately names the surface as the offer/negotiation one, distinguishing it from the buy-now siblings. An agent can tell this apart from get_ticket_listings or search_events 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 concrete triggering examples ('what's open near me this weekend'), names both downstream actions (make_offer_on_listing, buy_listing_now), and explicitly states when NOT to use it: for a plain buy-now at asking price, use search_events and get_ticket_listings. That is a full when/when-not/alternatives statement.

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

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

Goes well beyond the destructiveHint=true annotation: it discloses that confirm=False places no bid, that only confirm=True returns success=true, that the tool requires auth plus write:bids scope, and that real money is at risk. This is precisely the extra context annotations cannot express for a destructive 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?

Dense but front-loaded: source, then the two-phase rule, then guardrails, then alternatives. It is a single long paragraph and the security/scoping sentences could be trimmed, but nearly every sentence carries actionable information.

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

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

For a destructive money-moving write with an output schema present, the description covers the flow, the preview semantics, auth scope, and sibling routing. Nothing an agent needs to invoke it safely is missing, and return values are left to the output schema as expected.

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 100% schema coverage the baseline is 3, and the description adds real meaning: the confirm flag's two-phase contract, the deprecation of amount_cents, and the unit rule that whole dollars are required and fractional-dollar bids are rejected. It does not elaborate on listing_identifier's provenance beyond pointing at list_open_listings, which the schema already covers.

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

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

States a specific verb and resource ('two-phase write on the XP live offer book' / 'make an offer on an open XP listing') and distinguishes it from browse/discovery and buy-now siblings. An agent can tell immediately this is the bid-placement tool, not a listing lookup or purchase.

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 ('user wants to make an offer on an open XP listing'), when-not ('do not use for browse / discovery'), and named alternatives ('for standard buy-now ticket purchases... use search_events and get_ticket_listings'). It also mandates the preview-then-confirm sequencing rather than leaving it 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?

Goes well beyond the annotations by disclosing idempotency ('sets the state you pass rather than toggling, so repeating a call is safe'), scope of effect (only this user's view, nothing changes for seller/other buyers), and the auth requirement. This is exactly the extra context annotations don't carry.

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

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

Front-loads the when-to-use triggers before the behavioral caveats, which is the right order. It is dense but each clause carries information; the enumeration of example phrases is a touch long for the marginal benefit.

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 described, and the description fully covers scope, safety, idempotency, and auth. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% so the schema already documents both params; the description still adds value by explaining the state-set semantics of 'muted' and the unmute direction. Slightly above the baseline given the semantic clarification.

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 (mute/unmute a listing) and clearly bounds the effect to the user's own view of the live offer book. An agent can distinguish it from siblings like make_offer_on_listing or cancel_my_listing 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?

Provides explicit trigger phrases ('hide this one', 'stop showing me that', 'unmute that listing') and a scenario ('after deciding not to make an offer'). It also disambiguates the mute vs unmute direction, leaving little to inference.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description adds substantially more: the two-phase confirm gate, the fact that only confirm=True returns success=true, the required auth + write:listings scope, and who the actor is (seller rejecting a buyer's offer on their own listing). That is exactly the extra context annotations cannot convey.

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

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

Front-loaded with the source system and the two-phase rule before the supporting details. It is somewhat dense and the repeated 'two-phase' phrasing plus the final seller-facing sentence are slightly redundant, but 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?

Output schema exists so return values need not be explained. For a destructive, auth-gated, three-required-parameter mutation, the description covers trigger, safety protocol, permissions, and actor role — an agent has everything needed to call it correctly and safely.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by tying confirm=False to a preview and confirm=True to an actual reject that is the only path to success=true, and by positioning offer_uuid/identifier in the seller's listing 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?

States a specific verb (reject) on a specific resource (a buyer's offer/bid on the seller's own listing), plus the underlying system ('XP live offer book'). It is trivially distinguishable from the sibling accept_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?

Gives an explicit when-to-use trigger (authenticated seller rejecting a bid, with the 'reject the lowball offer' example) and a hard when-not/procedural rule: never call without the two-phase preview-then-confirm flow. The preview/confirm sequencing is spelled out step by step.

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

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

Annotations declare destructive=true/readOnly=false, and the description goes well beyond them: it states that existing fills are completed purchases and are not undone, discloses the two-phase confirm=false preview vs confirm=true commit behavior, and notes auth is required.

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 usage trigger, then effect, then irreversibility, then the phase model and auth requirement. Every sentence carries distinct operational information with no padding.

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?

Coverage is complete for a two-param mutation: trigger, effect, reversibility limits, confirmation protocol, and auth need are all stated, and an output schema exists so return values need not be described.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the confirm preview/commit semantics. The description largely restates the two-phase behavior rather than adding new parameter meaning, 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?

Names a specific verb+resource ('rescind' a 'standing offer') and immediately bounds the effect ('closes it to new fills'). It also points to the alternative path when the user instead wants to bid on something open, which separates it from the make_offer/cancel_my_offer family.

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 trigger conditions are given via user phrasings ('cancel that standing offer', 'stop waiting on those') plus the routing rule to an open-listing offer when that is the real intent. This is unambiguous when-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered; the description adds what comes back ('event cards from the XP catalog with a fee-inclusive price preview') and its intended purpose ('browsing and navigation'). It doesn't discuss result limits, pagination, or empty-result behavior, but those are partly covered by the output schema and the limit 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?

Four sentences, zero waste, and front-loaded: what it does, what it returns, then alternatives and exclusions. Every sentence carries a distinct routing or scoping fact.

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 catalog search with an output schema, full parameter documentation, and clear sibling boundaries, the description supplies everything an agent needs to select and invoke it correctly, plus explicit negative scope.

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 earns extra credit by illustrating the natural-language query semantics with concrete examples ('shows near me this weekend', 'Taylor Swift tour dates') and listing the entity dimensions the query can target. It adds interpretation guidance the schema's one-line query description does not.

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 ('Catalog search ... find live events on XP') and names the concrete entity types (concerts, sports, theater) and search keys (performer, team, venue, city, keyword). It explicitly distinguishes itself from search_market, search_performers, and search_venues, so an agent can route without opening any schema.

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

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

Gives explicit when-to-use ('discovery: find live events'), when to switch ('what an event is trading at ... use search_market'; 'look up a performer or venue by name ... use search_performers or search_venues'), and hard exclusions ('Not for scores, news, standings, or non-ticketed listings'). Nothing is left to inference.

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

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

Annotations already cover read-only, non-destructive, closed-world safety, and an output schema exists, so the description isn't carrying the safety burden. It still adds real behavioral context beyond the annotations: that prices are fee-inclusive get-in prices, that open-listing counts signal offer viability, and that the read is 'live' rather than cached.

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

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

Front-loaded with what the tool returns, then routing, then exclusions — a sensible information order with no filler sentences. It runs slightly long because the sibling routing is repeated across three sentences (search_events twice, list_open_listings once), which costs a bit of tightness.

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

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

For a search tool with a full output schema, the description supplies everything an agent needs to select it correctly: scope, price semantics, sibling routing, and exclusions. Return-format explanation is exempt thanks to the output schema, so nothing material is missing.

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

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

Schema coverage is 100%, so all six parameters including date filters and cbsa synonyms are already documented; that sets the baseline at 3. The description adds only indirect guidance via example queries ('cheap seats near me', 'season opener'), which hint at natural-language query phrasing but add nothing about date resolution or limit behavior beyond the schema.

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

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

States a specific verb and resource ('live market read for an event') plus the exact payload: fee-inclusive get-in price and count of open fan listings. It explicitly contrasts itself with search_events and points to list_open_listings for the listing-level view, so an agent can place it among siblings without opening schemas.

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

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

Gives an explicit positive trigger ('whenever price is the question or the user might make an offer rather than pay the asking price') with concrete example phrasings, plus explicit negative routing: search_events for plain discovery, list_open_listings for the listings themselves, and a hard exclusion for scores/news/standings. Both the when and the when-not are named, with 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and world-scope are covered; the description usefully adds that results are catalog performer cards rather than event listings, plus the two-step pairing workflow. However it says nothing about result ordering, pagination, or what happens when no match clears min_similarity, so it adds only moderate value beyond the 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?

Four sentences, each doing distinct work: what it does, when to use it with examples, what it returns and how it chains, and when not to use it. Purpose is front-loaded and there is no filler.

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

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

An output schema exists, so return values needn't be explained, yet the description still contributes the key distinction (performer cards, not events) and the chaining workflow with search_events. For a six-parameter read-only search with full schema coverage, nothing an agent needs to select or 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% (all six parameters, including query, genre, sport, limit, min_similarity, include_score, are described in-schema), so the baseline applies. The description's phrase 'by name' loosely orients the query parameter but adds no format, syntax, or filter-combination guidance beyond what the schema already provides.

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 + resource + scope: 'Find a performer (artist, team, comedian) on the XP marketplace by name.' It also explicitly disambiguates the output ('Returns performer cards from the XP catalog — not events'), which distinguishes it from search_events and search_venues without the agent needing to open a schema.

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

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

Gives explicit trigger conditions with examples ('tickets to Taylor Swift', 'Lakers season opener'), an explicit exclusion ('Do not use for general events near me queries'), and names the alternative sibling search_events for both the exclusion case and the follow-on case.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered by structured data. The description adds real value beyond that by defining what the result set is (catalog venue records, not tickets) and what it is not for, which prevents the most likely misuse. It says nothing about pagination or result volume beyond the schema's limit field.

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 sentences, front-loaded with the usage trigger, followed by output scope and then the exclusion. No filler and nothing repeated from the 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?

Output schema exists, so return-value detail is not needed, and the description covers source, scope, and the key sibling routing. The one gap is that get_venue_details, which an agent would call after finding a venue, is never referenced despite both tools being in the sibling set.

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 synonym hints for city/metro and state format, so the schema carries parameter meaning. The description only echoes the query dimensions (name, city, area) without adding filtering semantics such as how city and metro interact. Baseline 3 is appropriate.

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

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

States a specific verb and resource ("find a venue by name, city, or area") and pins the scope ("venue records from the XP marketplace catalog — not tickets"). It explicitly separates itself from get_ticket_listings, so an agent can route without opening either schema.

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

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

Gives concrete trigger utterances ("venues near me", "arenas in Brooklyn") plus an explicit negative case: do not use for ticket prices once the event is known, call get_ticket_listings instead. Both the when and the when-not are named with an alternative.

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 (which only flag it as a non-destructive write) by disclosing the approval workflow: public sources go live immediately unless an admin disabled auto-approval (then they wait for review), and private ones are only readable by linked nodes. It also names the return fields and the rejected-with-reasons behavior. 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?

Three tight sentences: purpose first, then approval/visibility behavior, then return shape. Every sentence carries information and nothing is padded.

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

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

With an output schema present, full input schema coverage, and annotations declaring the mutation profile, the description supplies exactly the missing behavioral context (approval flow, node visibility) 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?

Schema description coverage is 100%, and the schema already documents the sources array structure and agent_name semantics in detail. The description adds no parameter-level detail beyond that, 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 (suggest) and resource (groups/subreddits/searches where people sell tickets) that clarifies the tool's output well beyond the name. However, it does not distinguish this from nearby siblings like add_my_sources or submit_seller_leads, so an agent must infer the boundary.

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

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

Usage is implied by 'suggest new groups,' but there is no explicit guidance on when to use this versus add_my_sources or submit_seller_leads, nor any stated prerequisites. The agent can guess, but the choice among similar-sounding tools is not made 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 declare it is a non-destructive write; the description adds genuinely new behavior: dedup with first-finder credit, rejection with index/reason, a 72h staleness window, and canonical URL requirements. Some of this overlaps the output schema's rejected array, but the credit and resubmission semantics are not in structured fields.

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

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

Three short sentences with the core instruction front-loaded, then return shape, then the one prohibition. No filler; every clause carries a rule an agent must obey.

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?

Output schema exists so return values need not be spelled out, and the description still summarizes them usefully. What is missing is the failure/retry path for assignment_id mismatch or oversized lead batches, though both are partially covered by the schema.

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

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

Schema description coverage is 100% and the schema already documents leads, assignment_id, and could_not_read in detail, so the baseline is 3. The description adds only the implicit 'empty leads is valid' case and does not clarify field-level semantics beyond the schema.

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

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

States a specific verb and resource ('Submit what you read for one listening job') and names the counterpart tool by implication via assignment_id, distinguishing it from read-side siblings like get_listening_assignment. An agent immediately knows this is the write-back step of the listening workflow.

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 'Call once per assignment, even with no posts' and 'Do not resubmit rejected posts unchanged', which are real usage rules an agent would otherwise get wrong. It does not explicitly contrast with submit_discovered_sources or say what to do between assignments, so it falls short of full when/when-not guidance.

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