XP MCP

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 already declare readOnlyHint=true, non-destructive and closed-world, so the safety bar is low — yet the description adds genuinely non-obvious behavior: calling it first swallows the 401 and blocks the MCP client's OAuth trigger. It also discloses the return contents (authenticated boolean, tier roles, wallet flag) and guarantees no raw tokens are exposed.

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 strong constraint 'Use ONLY when...', followed by the counter-instruction and the reason. Dense but every sentence carries a distinct rule; nothing is repeated or 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 the description needn't enumerate return fields in detail, but it still summarizes them and adds the crucial anti-preflight warning. For a zero-param, read-only status tool, an agent has everything needed to decide when and when not to call it.

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

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

The input schema has zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. It correctly implies no inputs are needed by framing the call as a state read.

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

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

States a specific resource (XP marketplace sign-in state) and a narrow verb (report whether the user is authenticated). Explicitly distinguishes itself from the many protected sibling tools by forbidding use as a preflight before account/my tickets/wallet/referral/order tools.

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

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

Gives explicit trigger conditions (user asks 'am I logged in?' or wants state re-checked after AUTH_REQUIRED) and explicit exclusions (do NOT call as preflight before protected tools). Names the alternative behavior: call the protected tool directly and let the client handle the 401/OAuth flow, with the rationale for why.

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, but the description goes well beyond them: it discloses that confirm=true immediately moves money out of the caller's XP USDC balance, commits the seller, requires auth, and that a stale ask_per_ticket_usd causes refusal so the buyer never pays an unseen price. That is exactly the irreversibility and price-protection context an agent needs before a destructive 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?

Front-loaded with the resource and the core use case, then the safety-critical two-phase mechanics. Slightly redundant — 'the money leaves the caller's XP USDC balance' and 'Pays from the caller's XP USDC balance' say the same thing twice — but no sentence is wasted 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?

Output schema exists so return values need no explanation; annotations cover the safety profile; the description closes the remaining gaps — auth requirement, payment source, the preview/confirm contract, and the stale-price failure mode. Nothing needed to invoke this destructive purchase 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 baseline is 3; the description still adds value by explaining the preview-then-buy relationship between confirm and ask_per_ticket_usd and by clarifying that the rail parameter is irrelevant for fan listings (only buy_tickets uses x402). It largely restates the schema's own wording for ask_per_ticket_usd rather than extending it, so not 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 and resource — buying a fan resale listing outright at the seller's published ask — and immediately contrasts it with negotiating, which implicitly routes to accept_offer. The parenthetical example utterances ('buy it now', 'take it at the ask') make the intent match unambiguous against the 30+ 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 explicit when-to-use (authenticated buyer, listing has an asking price) and when-not (negotiating, i.e. offer-based flows), and names the alternative rail explicitly: 'the x402 rail does not apply to fan listings, only to buy_tickets.' The two-phase confirm=false/confirm=true protocol is spelled out as operational guidance.

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

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

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?

Annotations declare a destructive mutation; the description goes well beyond by documenting the mandatory two-phase confirm/preview flow, the auth and write:bids scope requirement, and that only confirm=True returns success=true. That is precisely the extra context an agent needs before invoking 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?

Front-loaded with purpose and the critical two-phase warning; the alternative-routing and browse exclusion are useful but border on extra bulk. Slightly long, though nearly every clause carries operative 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 annotations covering safety and an output schema covering return shape, the description supplies the remaining essentials: confirm semantics, auth scope, identifier resolution, and sibling routing. 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 mentions passing bid_uuid or a buyer swap id with server-side resolution, but this only restates what the schema's property descriptions already say, adding no new 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?

Names a specific verb and resource ('cancel... offer') scoped to the caller's own outstanding bid on XP's resale book, and explicitly distinguishes it from cancel_my_open_offer. An agent can identify the operation and the domain 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 use conditions (authenticated buyer rescinding an outstanding offer), names the sibling to use for cross-event open offers, and routes buy-now purchases to search_events/get_ticket_listings. When-to-use and when-not-to-use are both spelled out.

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

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

Annotations already flag destructiveHint=true, but the description adds substantial context beyond them: the offer closes to new fills while already-executed fills remain completed purchases, the two-phase confirm=false/confirm=true flow, and the auth requirement. This is exactly the information an agent needs before committing an irreversible action.

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?

Five short sentences, each doing distinct work: trigger examples, effect, irreversibility caveat, sibling disambiguation, two-phase protocol, auth. Zero filler and correctly front-loaded.

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

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

For a destructive two-parameter mutation with an output schema and destructive annotation, the description covers the effect, what is not undone, auth, disambiguation, and the preview path. Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100% and the schema itself documents confirm's preview/commit semantics and the open_offer_id source (list_my_open_offers). The description's 'confirm=false previews, confirm=true commits' restates the schema 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?

States a specific verb and resource ('cancel ... open offer resting on the XP marketplace') and explicitly distinguishes it from the sibling cancel_my_offer for single-listing offers. An agent can select this 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?

Front-loads the triggering condition with realistic user phrasings ('cancel that open offer for tickets to the game') and names the alternative (cancel_my_offer) with the exact condition that selects it. No inference required.

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

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

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 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 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 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?

The description adds substantial behavioral context beyond the annotations: hidden bid statuses, shared outcome-engine classification, pagination defaults and maximums, and the caveat that pagination.total only counts visible bids. It also confirms OAuth and read-only behavior, consistent with the annotations. This gives the agent enough context to avoid overstating completeness when has_more is 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 primary use case and then adds return classification, hidden statuses, pagination behavior, and auth requirements. Every part contributes useful information for invoking or interpreting the tool. It is appropriately sized for a paged, authenticated read tool with filtering nuance.

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

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

The description covers the key context an agent needs: who can use it, what bids are included or hidden, pagination behavior, and the caveat around has_more and pagination.total. An output schema exists, so return-value details need not be fully restated. Nothing important for correct invocation appears missing.

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

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

Schema coverage is 100%, so the input schema already documents limit and offset fully. The description repeats the default page size, maximum limit, and offset paging behavior but does not add much parameter-level meaning beyond the schema. The extra pagination caveat is useful, but it concerns output interpretation rather than the input parameters themselves.

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: an authenticated user viewing offers they placed on the XP marketplace. It also clarifies that results are classified as open or completed and that rejected/lapsed/refunded bids are hidden. It does not explicitly distinguish this tool from the close sibling list_my_open_offers, so it falls short of full sibling differentiation.

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

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

It gives clear usage context with example user utterances such as 'show my bids' and 'did any of my bids settle?'. It also states the OAuth requirement and the read-only nature. However, it does not name when to use a close alternative like list_my_open_offers or get_my_orders instead.

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

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

Annotations already declare readOnly/non-destructive/closed-world, yet the description adds genuinely new behavior: authentication requirement, newest-first ordering, and dollar-denominated money. The enumerated return fields are somewhat redundant with the output schema, 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 purpose, then triggers, then return shape, then exclusions — a well-ordered funnel with no filler. Every clause (ordering, currency, auth) carries decision-relevant 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?

Single optional param, output schema present, annotations present — the description covers the remaining gaps (auth, ordering, currency, sibling disambiguation) so an agent can select and call this tool with no further 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?

Only one optional parameter with 100% schema coverage describing range (1-50) and default (20), so the schema already does the work. The description says 'newest first' but adds nothing about the limit parameter itself; 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: 'Show the authenticated user their own orders on the XP marketplace and where each one stands.' The scope (own orders, with status) is immediately distinguishable from the seller-side and ticket-wallet siblings named later.

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

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

Gives concrete trigger utterances ('where is my order', 'did my tickets go through', 'what did I buy for Saturday') and explicit negative routing to get_my_tickets, list_my_listings, and get_my_offers with the reason for each exclusion.

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

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

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 declare readOnly, non-destructive, closed-world, so the safety profile is covered; the description adds the auth requirement and the required read:bids scope, plus the return shape (one row from the live offer book), which annotations cannot express. It stops short of disclosing staleness/freshness of the live book or any rate limits.

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

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

Dense but front-loaded: the resource, the trigger condition, and the exclusion all arrive early. Slight redundancy between 'offer/negotiation surface' and the trailing search_events/get_ticket_listings routing sentence, and the 'From XP's connected resale order book' opener is a fragment that costs a beat.

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

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

An output schema exists so return values need not be explained, and the description still covers auth, scope, single-record semantics, and alternatives. Only minor gap is it never states what happens if the identifier refers to a listing that is no longer open.

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

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

Schema description coverage is 100% and there is a single parameter whose schema text already says 'Public listing identifier from list_open_listings.' The description restates the identifier requirement and adds the sibling provenance context, but adds no format or validation detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource: retrieve the full record for a single open listing from the XP resale order book, returning one row. It explicitly distinguishes itself from buy_listing_now, get_open_offer, and get_ticket_listings, so an agent can route 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?

Gives a concrete precondition ("a listing identifier is in hand"), a buyer intent that selects it, and names the alternatives with the condition that picks them ("for a plain buy-now at the asking price without an offer, use search_events and get_ticket_listings instead"). Both when-to-use and when-not-to-use are 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, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds value beyond them: it states auth is required and that the tool returns offers 'at any status' along with their fills, which tells the agent the result may include terminal states and fill history. It does not discuss rate limits or edge cases such as an unknown id.

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, then the return behavior, then the auth requirement – each sentence contributes. Slightly dense with the quoted user phrasing ('did that offer get my tickets'), 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?

With an output schema covering return values and annotations covering safety, the description supplies exactly the remaining gaps an agent needs: when to call it, how it differs from the list sibling, the status coverage, and the auth requirement. 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% and the single parameter is fully documented in the schema (the standing_bid_id, sourced from list_my_open_offers). The description adds no further semantics about the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('get one specific open offer on the XP marketplace') and immediately frames the answerable questions (filled? how much left? did it get my tickets). It is clearly distinguishable from list_my_open_offers, which the description explicitly contrasts against.

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 the user asks about one specific open offer' and names the sibling it is not (list_my_open_offers), plus the condition that selects this tool over it: filled and rescinded offers that the list tool does not show. That is explicit when-to-use and when-to-use-the-alternative 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 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 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 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 mark this as a read-only, non-destructive, non-open-world operation. The description adds useful behavioral context: it defines what an open offer does, states that only live offers are returned, explains where filled and rescinded offers can be found, and 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?

The description is front-loaded with the primary usage condition and then adds the minimum necessary clarifications. Every sentence contributes to distinguishing this tool from siblings or explaining the live-only scope.

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

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

With zero parameters, a full output schema, and annotations covering safety, the description provides everything needed: when to call it, what it returns conceptually, how it differs from related tools, and the auth prerequisite.

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

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

The tool has zero parameters, so there are no parameter semantics for the description to explain. Baseline 4 is appropriate; the description correctly focuses on behavior and scope instead.

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

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

The description states a specific resource and scope: offers the user has resting on the XP marketplace, live offers only. It also distinguishes this from related tools by explaining that filled offers become tickets (`get_my_tickets`) and rescinded offers are reachable via `get_open_offer`.

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

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

It gives an explicit triggering condition ('when the user asks what offers they have resting...') and clarifies when not to use it for filled or rescinded offers. It points to `get_my_tickets` and `get_open_offer` for those cases.

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), so the bar is lower; the description still adds real value by disclosing the auth requirement and required read:bids scope, and by framing this as the offer/negotiation surface rather than a plain marketplace browse. It does not discuss result volume or pagination, 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?

Front-loaded with what the tool is, then use case, then auth, then the disambiguation from siblings; each sentence carries information. It is dense and long-ish but no sentence is filler, and the exclusion clause at the end is the one an agent most 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?

Ten optional parameters with full schema coverage, an output schema, and read-only annotations mean the structured fields carry the detail; the description supplies the missing dimensions — auth scope, negotiation semantics, and sibling routing. Nothing an agent needs to select or call this correctly is absent.

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 every parameter (including the deprecated micro-USDC amounts and the whole-listing vs per-ticket distinction) is already documented. The description only restates 'filterable by event, performer, and amount', adding no syntax or semantics beyond the schema — 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 — lists open resale listings from XP's connected order book that are open to offers — and names the exact alternative surface (search_events + get_ticket_listings) for plain buy-now. An agent can distinguish it from search_market and get_ticket_listings 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 concrete buyer-intent triggers ('what's open near me this weekend', 'open listings with active offers'), names the follow-up tool (buy_listing_now), and explicitly excludes the buy-now-without-offer case with a pointer to the right siblings. When-to-use, what-to-do-next, and when-not-to-use are all 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?

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?

Beyond the readOnly/openWorld=false annotations, the description discloses substantive behavior: parking listings and cancelled events never match, tribute/themed/inspired shows only match on explicit mention, postponed or >2-year-out dates count as TBD, duplicate listings collapse to one, and same_day means within 24 hours. These are exactly the operational rules an agent needs and none are in the annotations or schema.

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

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

A large share of the text enumerates return fields (`match`, `verdict`, `facts`, `score`, `why`) that an output schema already declares, which is wasted budget. The genuinely valuable matching rules are buried mid-paragraph in a dense wall of prose, so the most decision-relevant content is not front-loaded.

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

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

For a fuzzy natural-language resolution tool this covers the hard parts: candidate ranking, ambiguity signaling, disqualifiers, date edge cases, and verdict reasons. With annotations carrying safety and an output schema carrying shape, only recovery guidance (e.g., narrow with city/venue and retry) and a gloss on "XP" are 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 performer/city/venue/date_text/event_date are already documented with examples; the baseline is 3. The description adds only the implicit hint that inputs are 'the words the post uses' (i.e., verbatim, unnormalized text) and that XP, not the caller, decides the match — no per-parameter detail 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?

"Find the XP event a post means, from the words it uses" gives a specific verb (resolve/find) and resource (event) plus the input source (free-text post), which distinguishes it from structured siblings like search_events or search_performers. It stops short of naming any sibling explicitly, and "XP event" is internal jargon an agent may not know.

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 text is dominated by match-resolution policy (what qualifies, what never matches), not by when-to-use guidance. Nothing states when to reach for this over search_events or get_event_details, nor what to do when the result is `not_in_catalog` or `ambiguous` — the agent must infer routing from the tool name alone.

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.