Wall Marketing

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context by specifying what categories of data are surfaced (spend, remaining balance, approval rules, payment method status) and that it should precede a booking. It stops short of noting auth scope or freshness, and 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?

Two sentences, zero filler, front-loaded with the data categories and closed with the one operational directive. Every clause earns its place.

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

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

With no parameters, a rich output schema handling return values, and annotations covering safety, the description needs only to convey scope and timing — which it does. It is essentially complete, though a note on when the data is refreshed would be the only upside.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. The baseline for a parameterless tool is 4.

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

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

The description names a concrete resource (the account's spending limits) and enumerates the specific facets it returns — spent, remaining, approval rules, saved card. That is far more than a restatement of the name. It doesn't explicitly distinguish itself from siblings like advertiser.bookings.quote, but the resource is clearly distinct.

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?

"Check this before booking" gives explicit, actionable timing guidance that ties this read-only tool to the booking workflow. There are no stated exclusions or named alternatives, which keeps it short of a 5.

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

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

Annotations only declare the write/side-effect profile; the description goes further by disclosing automatic conversion to 800×480 e-paper with a fixed palette, a legacy six-colour render, and content moderation for nudity and profanity. It does not say what happens when moderation rejects the image (error vs. soft failure) or that re-uploading creates a new creative each time, which is the main residual 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?

Dense but front-loaded: the accepted input sources come first, then processing, then return value, then practical content tips. Nearly every clause carries information; the firmware version note is slightly buried mid-sentence but no sentence is filler.

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

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

For a 5-parameter, open-world write tool with an output schema, the description covers input forms, transformation, moderation, and returns adequately. The missing piece is failure semantics (moderation rejection, oversized/invalid URL) and the implicit either/or requirement on the two image sources.

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 baseline is 3; the description adds semantic context above that by explaining that the six-colour 'render' path only matters for screens on firmware before 0.16.0 and that every upload is also converted to the 1,307-colour palette. It still doesn't clarify that exactly one of image_url / image_base64 must be supplied, despite zero required parameters.

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

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

States a specific verb and resource (upload advert artwork) and immediately narrows the accepted inputs (public https PNG/JPEG URL or base64). It also describes the downstream transformation pipeline, so an agent knows exactly what the tool produces and how it differs from every sibling, none of which handle creative assets.

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?

Useful practical guidance is given ('Photos work; large, high-contrast words read best from a distance') and the schema covers the fit/render trade-offs, but the description never states when to use this versus not, nor any prerequisites such as an existing booking or screen. With no competing sibling there is little to disambiguate, but the absence of preconditions keeps this at minimum-viable-plus.

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

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

Annotations mark it as non-read-only, non-idempotent, non-destructive. The description adds real behavioral value beyond that: it is sandbox-restricted, only applies to bookings in awaiting_approval, and mirrors an action normally performed by the account holder. It doesn't detail failure behavior for bookings in other states.

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

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

Two tight sentences with the sandbox constraint and state precondition front-loaded. Nothing is redundant 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 return values needn't be explained. The description covers the sandbox scope and the awaiting_approval precondition, which are the key invocation prerequisites; only error/edge behavior is left implicit.

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

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

One parameter with 100% schema coverage, where the schema already states the booking_id source (create or list). The description adds no syntax, format, or semantics beyond what the schema documents, 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 (approve), resource (booking), and precondition (awaiting_approval), plus the sandbox-only scope. It contrasts with the live path ('Live bookings can only be approved by the account holder'), which distinguishes it from siblings like advertiser.bookings.pay or update.

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?

Makes the use case explicit: only for sandbox testing so the rest of the flow can be exercised, and clarifies that live approvals are out of scope for this tool. It does not name a sibling as an alternative, but the when/when-not condition is clear.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: an unpaid booking cancels immediately, while a paid one is deferred to a human staff member, meaning the outcome is not deterministic. It doesn't mention permissions or confirm the response shape, keeping it from a 5.

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

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

Two short sentences with no filler, and the core behavioral distinction (unpaid vs paid) is front-loaded in the first sentence. Every clause carries 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?

An output schema exists, so return values need no explanation, and annotations carry the safety profile. The description supplies the key non-obvious nuance about human-mediated refunds for paid bookings, leaving only minor gaps like permission requirements.

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

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

Schema description coverage is 100%, so both parameters are already documented by the schema. The description hints at the reason parameter's role ('for staff deciding a refund') but adds no syntax or format detail beyond what the schema provides, 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 (Cancels) and resource (a booking), and crucially splits the behavior by payment state, which makes it distinguishable from siblings like pay, approve_sandbox, and update. It stops short of explicitly naming any sibling, so it's a clear 4 rather than 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 paid vs unpaid branching gives real context on what invoking this tool will do in each case, which implicitly guides when to use it. However, no alternative tool is named (e.g. pay, update) and there are no explicit when-not-to-use conditions, so it stays at implied usage.

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 (which already state write, non-destructive, idempotent, closed-world), the description discloses spending-limit enforcement, three possible payment/approval outcomes with the awaiting_approval status, staff pre-review for six sensitive categories, immediate scheduling on payment, and that next_step in the result should be read. Idempotency behavior is stated in effect ('never books twice'), which is richer than the boolean hint alone.

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

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

The purpose and its scoping (venue exclusion) are front-loaded, then the payment/approval branches, then category review, then idempotency. It is dense but nearly every clause carries decision-relevant information. Minor tightening is possible in the approval/payment sentence which is somewhat run-on.

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

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

For a high-stakes write with branching payment outcomes, the description covers what an agent needs: prerequisites, approval paths, staff-review delay, scheduling behavior, result field to inspect, and idempotency. With an output schema present and annotations covering safety hints, 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%, so the schema already documents every parameter (including the category enum, quote reuse window, and idempotency key). The description largely restates those semantics rather than adding new parameter-level detail, so the baseline of 3 applies.

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

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

The first sentence gives a concrete verb and resource (book a quote/advert with a creative), and the rest of the description situates it precisely in the booking life-cycle, distinguishing it from advertiser.bookings.quote, .pay, and .approve_sandbox. An agent can identify this as the terminal step that actually commits a booking and schedules screens.

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 implicitly establishes prerequisites and sequencing: a quote and uploaded creative are required, and it explains the two downstream branches (immediate card payment / payment_url, or email approval to awaiting_approval). It also clarifies that venues play no part in booking, steering away from host/ambassador venue tools. It stops short of explicitly naming alternative tools or when-not-to-use conditions.

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 the safety profile is covered. The description's remaining content (the returned fields) is redundant with the existing output schema and adds no behavioral context such as rate limits, side effects, or staleness of the approval/payment state.

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 a single terse sentence fragment with no waste, but it leads with no verb or purpose statement and is arguably under-specified rather than well-structured. Efficiency is fine; front-loading of intent is weak.

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?

Because an output schema exists, return values need not be explained, and annotations cover read-only semantics; the single required parameter is documented. What is missing is the selection context relative to the many sibling booking tools (list, report, quote, update), which leaves the description minimally viable rather than 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 description coverage is 100% and the single parameter is fully documented, including its provenance ('From advertiser.bookings.create or bookings.list'). The description adds nothing beyond the schema, so the baseline of 3 is appropriate.

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

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

The description enumerates the data returned ('status, placements, approval and payment state, and next_step') but never states the verb/action (retrieve/fetch), and it names no sibling. An agent can infer this fetches a booking's details, but it is a noun fragment rather than a specific verb+resource statement, and it does not distinguish itself from advertiser.bookings.list or advertiser.bookings.report.

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

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

There is no explicit guidance on when to call this versus advertiser.bookings.list (which also surfaces bookings) or advertiser.bookings.report. Usage is only implied by the name and the booking_id parameter; no exclusions or prerequisites (e.g., auth/role) are stated.

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

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

Annotations already carry the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower. The description adds real context beyond them — result ordering (newest first) and the presence of status and next_step fields — but says nothing about paging behavior or how far back 'recent' reaches.

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

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

A single short sentence that front-loads the resource and scope with zero filler. Nothing is wasted and nothing is buried.

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 simple read-only list with a full output schema and complete parameter descriptions, the definition covers the essentials — scope, ordering, key returned fields. Only minor gaps remain (pagination and the meaning of 'recent'), which the output schema partly absorbs.

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 only two parameters, so the schema already documents the limit default and the status enum. The description adds no filter syntax or semantics beyond what's in the schema, so the baseline 3 applies.

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

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

The description names a specific resource (bookings), scopes it (for this account), and states the sort order (newest first), so an agent immediately knows this is a broad collection read. It stops short of explicitly distinguishing itself from the sibling advertiser.bookings.get, which returns a single booking.

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

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

Usage is only implied: 'Recent bookings for this account' suggests a broad listing, which contrasts implicitly with advertiser.bookings.get, but the description never says when to prefer one over the other or note any exclusions. No prerequisites or pagination guidance is given.

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

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

Annotations already declare this is a non-read-only, non-destructive, idempotent, open-world call, but the description adds the actual behavior: it charges a saved card, otherwise returns a fresh payment_url for the account holder. That branching outcome is genuine value beyond the flags. It leaves failure modes (already-paid booking, declined card, whether a retry risks a double charge) unstated.

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

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

One sentence that front-loads the eligibility precondition before the behavior, with no filler. Every clause earns its place.

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 covers precondition, branching behavior, and outcome for a two-param tool. What is missing is error/edge handling (booking not in a payable state, card on file declined) and any auth or permission 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?

Schema description coverage is 100% and both params (booking_id, use_saved_card) are already documented with defaults, so the baseline would be 3. The description goes further by spelling out the consequence chain of the saved-card branch versus the payment_url branch, which is useful interpretation the schema does not give.

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 (charges/pay) on a specific resource (a booking) and scopes it to bookings 'awaiting payment or whose payment link expired'. That precondition alone separates it from sibling bookings tools like create, cancel, quote, or approve_sandbox, so an agent can pick it without opening the schema.

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

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

Gives a clear when-to-use condition ('booking awaiting payment or whose payment link expired'), which is exactly the trigger context an agent needs. It stops short of naming when *not* to use it or pointing at alternatives, so it is not a full 5.

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

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

Annotations only give generic flags (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so credit goes to the description for disclosing the two facts an agent actually needs: the quote is time-boxed to 30 minutes and it does not reserve the screens. It stops short of explaining why the call is non-read-only or whether repeated calls re-price.

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

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

Three short sentences, no filler, and the most decision-relevant facts (price hold, no screen hold, exclusive end date) are front-loaded. Nothing needs to be skimmed past.

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 shape need not be described, and the description covers the principal caveats (price expiry, no inventory hold, date boundaries). It leaves one small gap: it never states that either items or venue_ids must be supplied, which matters given zero required parameters.

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% and the schema itself documents the exclusive end date, so the baseline is 3. The description lifts this by spelling out the exclusivity with a worked example (1 Nov booking = start 2026-11-01, end 2026-11-02), which is the single most error-prone input in the schema.

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

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

States a specific verb and resource ('Price a set of venues and dates') and immediately clarifies the non-committal nature of the result: it 'holds its price for 30 minutes (it does not hold the screens).' That behavioural distinction is what separates it from advertiser.bookings.create, so an agent can pick correctly without reading 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?

Usage is implied rather than stated: the price-check and 30-minute hold signal this is a pre-booking step, but the description never says 'use this before advertiser.bookings.create' or when not to use it. No alternatives or prerequisites (e.g. needing venue ids from venues.search) are given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds one genuinely useful behavioral note — 'No personal data about viewers' — which clarifies the privacy scope of the returned data, but says nothing about freshness, aggregation windows, or cost.

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

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

Two short sentences with no filler, front-loaded with what the report contains. The first sentence is slightly cryptic as a fragment ('Days each screen confirmed showing the advert') and could be tightened, 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 present, return values need not be explained, and the single parameter is fully covered. What is missing is the usage context that matters here — when to call this versus advertiser.bookings.get or list — leaving the definition adequate but not complete for disambiguation.

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 booking_id and its provenance (advertiser.bookings.create or bookings.list) are already documented. The description adds no parameter-level detail such as whether booking_id scopes to a single campaign/period, so the baseline 3 applies.

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

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

The description makes clear what the tool produces: per-screen confirmation days plus estimated view counts (a proof-of-display report, matching the title). It is clear, but it never states an action verb and does not distinguish itself from advertiser.bookings.get, which an agent could easily confuse it with.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as advertiser.bookings.get or advertiser.bookings.list. The only routing hint lives in the schema's booking_id description, not the tool description.

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 parenthetical that screens pick up new artwork at their next daily check-in is a genuinely valuable behavioral disclosure: it tells the agent the change is eventually consistent and not immediately visible. Annotations already cover the safety profile (non-destructive, idempotent), so the description is not obligated to restate it. It still omits what happens when both optional fields are supplied or neither.

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

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

A single sentence, front-loaded with the primary action and with every clause earning its place; the propagation detail is worth its parenthetical. It is slightly under-specified for a tool with two optional mutation paths, which prevents 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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. The remaining gap is invocation correctness: with only booking_id required, an agent is not told what happens if both creative_id and campaign_name are given, or if none is.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, setting the baseline at 3. The description adds the meaningful nuance that the two optional fields are alternatives ('or') and that creative_id is 'another creative', but the exclusivity is only hinted at rather than specified, so it does not rise above 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?

The description names two concrete operations on a specific resource: swapping a booking's artwork and changing its campaign name. That is far more informative than the title alone and cleanly distinguishes it from bookings.create, cancel, or pay. It does not explicitly contrast itself with siblings, 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?

Usage is implied by the two stated capabilities, and the schema points at bookings.upload_artwork as the source of a creative_id, giving an implicit prerequisite. However there is no explicit when-to-use/when-not guidance, no mention of which sibling to pick for other booking mutations, and no statement about calling this versus re-creating a booking.

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 the safety profile is covered by structured data. The description's remaining content mostly describes return values (details, price, booked ranges), and since an output schema exists it earns limited credit; the 'end dates exclusive' note is the one genuinely non-obvious behavioral detail it adds.

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

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

A single front-loaded sentence with no filler. Every clause (details, price, booked ranges, exclusive end dates) carries information, and the most important scope fact ('one venue') leads.

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 one-parameter read tool with annotations and an output schema, the description covers the essentials and does not need to explain return values. Minor gaps remain around failure behavior for an unknown venue_id and how it relates to the venues.search sibling, but nothing blocking.

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 exists and schema description coverage is 100%, with the schema itself stating the id comes from venues.search. The description adds no syntax, format, or constraint information about venue_id, so the baseline 3 applies.

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

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

The description gives a specific verb+resource ('One venue's details') and enumerates the payload (price, booked date ranges), so the agent knows exactly what comes back. It implies the single-venue lookup role next to advertiser.venues.search but never names or contrasts with that sibling, which keeps it out of 5 territory.

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

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

Usage is only implied: the 'one venue' scope suggests this is the follow-up call once you have a venue_id, and the schema hints the id comes from venues.search. There is no explicit when-to-use, when-not-to-use, or named alternative anywhere in the description text.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, and the description adds genuinely non-structured business context: each screen runs one advert at a time so a booking has the screen exclusively, and pricing is per screen per day in USD. It does not cover pagination behavior or how to page past the limit, which keeps it out of 5 territory.

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 what the inventory is before listing filters and units; nothing is padded. The opening domain sentence is slightly longer than strictly needed, but it earns its place by anchoring an otherwise opaque tool name.

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

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

With an output schema present and full annotation coverage, the description need not explain return values, and it supplies the missing conceptual context (what the screens are, exclusivity, price unit). The only unaddressed operational detail is result pagination/sorting beyond what the schema notes, a minor gap for a read-only search.

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 units ('in US dollars'), the near_latitude/near_longitude pairing, and the available_from/available_to range meaning. The description restates the filter set and the per-day USD pricing but adds no syntax, defaults, or interaction rules 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?

The description names a concrete action (find/filter) plus the exact resource (Wall Marketing e-paper screens placed inside venue doors), and enumerates the filter dimensions. The domain framing makes it unmistakably a discovery/list operation rather than the single-entity advertiser.venues.get sibling, and it pre-empts confusion about what 'venue' inventory actually is.

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

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

Filter choices (city/address, venue type, price, distance, free dates) imply the situations this tool fits, but there is no explicit when-to-use or when-not-to-use statement and no named alternative (e.g. advertiser.venues.get for a known venue id, or advertiser.bookings.quote for pricing a chosen screen). Usage is inferable, not stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the enumerated field set and a 'Terms version 2026-09-26' detail, but says nothing about permissions, freshness, or pagination that annotations leave open.

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

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

One front-loaded sentence that opens with the resource and then lists contents with no filler. It is a long enumeration but every element earns its place.

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 zero-parameter, read-only tool with full annotations and an output schema, the definition is essentially complete; the return-value enumeration is redundant with the output schema but not harmful.

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, which is the baseline-4 case; there is nothing for the description to disambiguate. The enumerated fields are return values rather than 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?

The description clearly identifies the resource ('your outreach team account') and enumerates the exact contents: status/trust tier, location, claims, balances, commission, and rules. The verb is only implicit (a read of the account), and it does not name any sibling tool, so it falls 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?

There is no explicit when-to-use, when-not, or alternative routing. Usage is only implied by the tool's self-evident 'me' account-summary nature, and it never points to ambassador.earnings.wallet or ambassador.account.set_location for related concerns.

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

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

Annotations already cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description still adds substantive context beyond them: the call mutates stored state by generating a venue list, and it spells out the filter criteria (busy, well-reviewed, no screen yet, unclaimed). It omits any auth/permission requirement, which keeps it from a 5.

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

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

Front-loaded with the action and only two sentences, with no filler preamble. The venue enumeration is long but each item is doing filter-criteria work, so it is defensible rather than padding.

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

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

An output schema exists, so return values need no explanation. The description usefully implies that an address or a lat/lng pair must be supplied even though the schema marks zero required parameters, which is an important disambiguation. It leaves unstated what happens when neither is provided and how a repeated call interacts with the previous list.

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 lat, lng, label and address. The description restates the address-vs-lat/lng alternative but adds no syntax, format, or precedence detail beyond the schema (e.g. what happens if both are supplied), 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?

Specific verb+resource: 'Set the area you are working' and it discloses the consequential side effect (building a suggested-venue list) rather than just the write. It also names the follow-up tool the agent should use to read the result, which separates it from the read-only siblings like ambassador.venues.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?

It gives a clear workflow: set the area first, then 'read them with ambassador.suggestions.' That is real routing guidance. It stops short of a 5 because there is no explicit when-not-to-use and the referenced sibling name ('ambassador.suggestions') does not exactly match the actual sibling (ambassador.venues.suggestions), which could send an agent to a non-existent tool.

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

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

Annotations already declare it non-read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real value beyond them by defining the amount affected (everything withdrawable) and the account-state prerequisites, which 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?

Two tight sentences with the action front-loaded and the preconditions trailing. Every clause carries information: scope, destination, and three requirements; 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?

An output schema exists, so return values need not be described, and annotations cover the mutation/idempotency profile. What remains for an agent to know before invoking  scope, destination, and preconditions  is fully present.

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

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

The tool takes zero parameters, so there is no parameter syntax or meaning for the description to supply; baseline 4 applies. The description correctly redirects the target configuration (payout details) to the dashboard rather than to an argument.

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 ("Request a payout") and narrows scope to "everything withdrawable, to the payout details saved on the outreach dashboard." An agent can distinguish it from host.earnings.withdraw by the ambassador/outreach framing, though no sibling is named 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 concrete gating conditions for successful use: identity verified, payout details set once on the dashboard, and at least the minimum confirmed. It does not name an alternative tool (e.g., host.earnings.withdraw) or state when not to use it, so it is clear context without explicit routing.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that: it enumerates the balance states returned, and clarifies that identity verification and payout details are configured elsewhere on the outreach dashboard while this tool only reports whether they are missing. That 'reports but cannot fix' boundary is the useful behavioral disclosure.

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

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

Two sentences, front-loaded with what the agent gets back, followed by the prerequisite/verification caveat. The parenthetical list of balance states is dense but each item is informative; there is no filler or restatement of the title.

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

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

For a zero-argument read tool with an output schema, the description covers the meaningful gaps: what is returned (balances, ledger, eligibility) and the one non-obvious behavior (it only surfaces missing verification/payout setup). Nothing an agent needs to call it 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?

The tool takes zero parameters, so the baseline is 4. The description correctly describes only output content and makes no claims about inputs, leaving nothing misrepresented.

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

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

The description names the concrete content of the resource: balances across four states, the commission/payout ledger, and payout eligibility. It implicitly distinguishes itself from the write-side sibling ambassador.earnings.request_payout by framing its role as 'whether a payout can be requested', but it never names that sibling or states a verb explicitly, so differentiation requires inference.

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

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

Usage is only implied: an agent can infer this is the pre-flight read before ambassador.earnings.request_payout, and that it reports missing verification/payout details. There is no explicit statement of when to call this versus the withdrawal/request tools, and no stated 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 only declare the generic write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true). The description goes well beyond that: it discloses external side effects (Google lookup and the same vetting pipeline as suggestions), the rejection conditions, the exclusivity rule, and the quota consequence ('Counts against your claim cap').

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

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

The core action and input form are front-loaded in the first sentence, with eligibility and cost following. It is a dense paragraph rather than bulleted, and the vetting-criteria list is long, but every clause 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?

An output schema exists, so return values need no explanation here. Given a 5-parameter, zero-required write tool, the description covers inputs, eligibility, rejection, and quota impact — everything needed to decide and call correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantic value the schema does not: it explains the either/or input contract (name and address, or place_id) for a tool where zero parameters are marked required. That tells the agent a valid call shape the schema alone leaves ambiguous.

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

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

States a specific verb and resource ('Add a venue that is not on our list and claim it'), plus the input basis (name and street address, or Google place_id). The 'not on our list' scoping cleanly separates it from ambassador.venues.claim and ambassador.venues.suggestions without needing to open their 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 clear conditions for use: the venue must be absent from the list, supplied via name+address or place_id, and it lists the vetting gates (operating, permitted category, no existing screen, review/rating/hours score) plus the refusal case for already-claimed venues. It never names a sibling tool as the alternative for the cases it excludes, which keeps it short of a 5.

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

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

Annotations only declare the mutation/idempotency profile; the description adds real behavioral context on top: the claim is time-bounded (a set number of hours) and quota-limited (a cap on concurrent holds, deferred to ambassador.account.me). It omits what happens after expiry or to the venue if the claim lapses, which keeps it below 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?

Three short sentences, each doing distinct work: what it does, the constraints, and the undo path. Front-loaded with the purpose and no filler.

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

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

An output schema exists, so return values need no explanation, and the description covers the lifecycle semantics (hold, duration, quota, release). It would be fully complete with a note on supporting permissions or quota-exhaustion behavior, but nothing essential for calling 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?

One parameter with 100% schema description coverage ('From ambassador.suggestions.'), so the schema already carries the meaning. The description adds no additional detail about venue_id beyond implying it is a suggested venue, which matches the baseline 3 for high-coverage schemas.

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

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

Specific verb ('Hold/claim') plus resource ('a suggested venue') plus a clear purpose ('so nobody else on the team does'). It cleanly separates claim from the sibling release and from add/submit by scoping it to suggested venues.

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 when-to-use condition (while you approach a venue, to block teammates) and names the escape hatch, ambassador.venues.release, for when it comes to nothing. It does not explicitly distinguish claim from ambassador.venues.add/submit or say when not to claim, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavioral context by naming the full status vocabulary (Claimed, Pending with sub-states, Confirmed, Rejected, Reversed, Released, Expired), which tells the agent what states it can expect to encounter.

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

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

A single sentence that front-loads the scope ('every venue you have claimed or submitted') and then spends its remaining words on the status enumeration, which is the one detail that genuinely helps. 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?

For a no-parameter, read-only listing tool with an output schema and readOnly/openWorld annotations, the description covers what is needed: what is listed and what statuses appear. Return shape is left to the output schema, which is appropriate.

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 is 4 and there is nothing parameter-related for the description to compensate for. No syntax, filtering, or pagination options are mentioned, but none exist to document.

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 (venues) scoped to the caller's own claims and submissions, and enumerates the pipeline stages returned. That scope word 'you have claimed or submitted' is what separates it from advertiser.venues.list and ambassador.venues.suggestions without 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?

Usage is implied rather than stated: it is clearly the 'see all my venues' call, but the description never says when to prefer it over ambassador.venues.suggestions, ambassador.venues.add/claim, or advertiser.venues.get, nor does it set any 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 declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds one behavioral fact beyond that — the venue returns to a shared pool and becomes available again — but says nothing about whether the claim is permanently invalidated, whether re-claiming is possible, or what confirmation is returned.

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

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

A single six-word sentence that is front-loaded with the action and result state. Nothing is wasted and nothing needs reordering.

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 no explanation, and there is only one required parameter. However, for a destructive (if idempotent) operation, the definition omits what happens to the claim record and whether the venue can be immediately re-claimed, leaving a real gap.

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

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

Only one parameter and schema description coverage is 100% ('From ambassador.account.me or ambassador.venues'), so the schema already carries the semantics. The description adds no further meaning about claim_id, which matches the baseline of 3 when the schema does the heavy lifting.

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

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

Names a specific action (release / give back) on a specific resource (a claimed venue), and 'back to the pool' clarifies the resulting state. It stops short of explicitly contrasting itself with the inverse sibling ambassador.venues.claim, but the verb+resource pairing is unambiguous.

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

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

There is no statement of when to call this versus ambassador.venues.claim, ambassador.venues.list, or add/submit, and no prerequisites (e.g. must hold a valid claim_id, must be the claiming ambassador). The usage is only weakly implied by 'give back'.

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 non-read-only, non-idempotent, open-world write, and the description adds real context beyond that: an agreement is dispatched to the venue by WhatsApp/email, a quality check runs, a screen ships, and the commission moves to pending then confirmed on first check-in. It stops short of describing failure/rejection behavior or reversibility, so not quite 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?

Three tight sentences, front-loaded with the precondition and outcome; each sentence adds a distinct fact (trigger, downstream flow, claim requirement, commission lifecycle). Slightly long for the payload but nothing is filler.

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

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

An output schema exists so return values need not be explained, and the description covers preconditions and consequences for a 6-required-parameter workflow tool. It leaves open the operational meaning of 'hold the claim' and what happens if the venue declines or the quality check fails, which would be helpful for a workflow step like this.

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 9 well-annotated parameters and 4 enums, so the schema fully carries parameter meaning. The description adds no per-parameter detail (e.g., venue_id sourcing, wall_location, agree_channel/contact_email interplay) beyond what the schema already states, 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?

Specific verb (submit) plus resource (venue) gated by a clear precondition (owner/manager agreed in principle), and it describes the resulting downstream flow. This distinguishes it cleanly from siblings like ambassador.venues.claim and ambassador.venues.add, which an agent can differentiate 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?

States the triggering condition ('once the owner or manager has agreed in principle') and the prerequisite 'You must hold the claim on the venue', which tells the agent what must be true before calling. It does not, however, name the alternative siblings (claim, release, add) or say what to do when the precondition is unmet.

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 is covered. The description adds behavior beyond that: results are ordered best-first, each carries rating/review count/distance/score, and a claim step is required before acting — context that meaningfully shapes how an agent uses the output.

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

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

Two tight sentences with no filler. The result shape and ordering are front-loaded, and the follow-up action is placed last where it belongs.

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 enumerate return fields, and annotations cover the safety profile; the description supplies the ordering and next-step semantics that structured fields don't. The only gap is the missing differentiation from ambassador.venues.list.

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 no parameters, so there is nothing for the description to disambiguate; per the baseline rule for zero-parameter tools this scores 4. The description does clarify that scoping comes implicitly from the caller's work location rather than an argument.

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 (venues suggested for your work location) and scope (best first), which is more precise than the bare name. It does not, however, distinguish itself from the closely-named sibling ambassador.venues.list, so an agent still has to guess which list to call.

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

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

The description gives one concrete workflow instruction — claim a venue via ambassador.venues.claim before approaching it — which is useful routing to a sibling. It says nothing about when to use this over ambassador.venues.list or advertiser.venues.search, so the primary selection decision 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 already establish readOnlyHint=true and openWorldHint=false, so safety is covered; the description goes further by disclosing the 30-day maturity rule and the external dependency on venue-portal identity/payout setup. It does not state anything about freshness, caching, or error conditions, 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?

Two sentences, both dense with distinct information — the first covers wallet contents and the maturity rule, the second covers preconditions. No filler, and the most decision-relevant content (what's in the wallet, whether withdrawal is possible) leads.

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 zero-parameter, read-only tool with an output schema already documenting the return shape, the description supplies exactly the missing pieces: the domain maturity rule and the external preconditions. Nothing an agent needs to call or interpret it 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?

The tool takes zero parameters, so the baseline is 4; there is nothing parameter-related the description could or should explain. The schema is trivially complete at 100% coverage.

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

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

The description enumerates the wallet's contents precisely: earned-from-adverts, matured (with the 30-day rule), paid, and withdrawal eligibility. An agent can tell this is the read-only state view rather than the sibling host.earnings.withdraw, though the sibling is only implied by 'whether a withdrawal can be requested' and never named.

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 supplies the operative context for the withdraw flow: a day's share matures after 30 days, and identity verification/payout details are configured on the venue portal, with this tool reporting if they are missing. That tells the agent when to call it as a precondition check, but there is no explicit when-not-to-use or direct pointer to host.earnings.withdraw.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, closed-world. The description adds real context beyond them: the call sweeps the full withdrawable balance (not a partial amount), funds go to the portal-saved payout details, and three gating conditions must hold. It does not say what happens when those conditions fail, which keeps it 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?

Two sentences, front-loaded with the action and scope, followed by prerequisites. No filler, no repetition of the title, and nothing that could be cut without losing 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?

An output schema exists so return values need not be described, and the prerequisites plus payout destination cover what an agent needs to decide and invoke. Minor gap: no statement of the failure mode or error when identity/payout details/minimum are not met.

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

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

Zero parameters, so the baseline is 4, and the description usefully explains the absence of an amount parameter by stating it withdraws 'everything the venue can withdraw' — an all-or-nothing semantic that an agent could not infer from an empty schema.

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

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

The description gives a specific verb ('request a payout') and resource ('everything the venue can withdraw') plus the destination (saved payout details). It is clearly distinguishable from the read-only host.earnings.wallet, though it does not name a sibling explicitly the way a top-tier definition would.

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

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

It states the preconditions for use: identity verified, payout details set on the portal, and at least the minimum withdrawable balance. That is solid context, but there is no explicit when-not-to-use guidance or named alternative (e.g. vs. ambassador.earnings.request_payout).

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 destructive/idempotent annotations, the description discloses the actual removal timing: a pending change is dropped immediately, while a backup already held by the screen is removed at its next check-in. It also explicitly bounds the blast radius (current WiFi unaffected), which is exactly the context an agent needs before invoking a destructive tool.

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

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

Three short sentences, front-loaded with the action and the originating sibling, then the deferred-removal semantics, then the safety boundary. No filler and nothing repeated from the title 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, annotations covering safety, and the parameter documented in-schema, the description covers the remaining gap well by explaining deferred removal and the unaffected current network. It does not say what happens if no backup exists, though the idempotent hint largely covers that.

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% with a single device_id parameter already documented as coming from host.overview, so the schema carries the load. The description adds no further meaning about the parameter, which is acceptable at this coverage level but earns only 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?

"Remove the backup WiFi set with host.screens.set_wifi" gives a specific verb (remove), a specific resource (backup WiFi), and ties it to the companion sibling that created it. An agent can separate this from host.screens.set_wifi 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?

The description makes clear this is the undo counterpart to host.screens.set_wifi and scopes the effect ("Its current WiFi is not affected"), which implicitly tells the agent this is not a full network reset. It stops short of an explicit when-to-use/when-not statement or naming an alternative for clearing the active network.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, and non-idempotent, so the safety profile is covered structurally. The description adds genuine behavioral context beyond that: it names the reviewer (Wall Marketing), promises prompt review, and discloses the outcome (the advert is removed from that screen if the objection is reasonable). It stops short of saying what happens if the objection is rejected or whether the report is reversible.

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

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

Two sentences, front-loaded with the action and followed by the process it triggers. Every clause carries information (who reviews, what happens next); no filler or repetition of the title.

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

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

An output schema exists, so the description need not explain return values. It covers the purpose, the trigger condition, and the downstream consequence of filing a report, leaving only edge cases (rejected reports, latency) implicit. Adequate for a 3-parameter, single-purpose reporting tool.

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

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

Schema description coverage is 100%, so device_id, order_id, and reason are already documented in the schema ('the screen, from host.overview', 'the advert's order_id', 'What is wrong with the advert'). The description adds no parameter-level detail, so the baseline 3 applies.

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

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

The description states a specific verb (object/report) and resource (an advert showing or scheduled on your screen), so the action is unambiguous. It doesn't explicitly differentiate from the sibling advertiser.bookings.report, but the host-side framing and the required device_id/order_id make the resource scope clear.

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 trigger context (report an advert already placed on your screen) and clarifies that venues do not book adverts, which is useful framing. However, it names no alternatives or when-not-to-use conditions, so routing between this and advertiser.bookings.report 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?

Adds substantial behavior beyond the annotations: the backup is applied at the screen's next check-in (every few hours), the failover swap semantics are spelled out, and the one-backup-per-screen replacement rule is disclosed. The annotations only cover idempotency and non-destructiveness, so this latency and state-transition detail is genuinely new information.

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

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

Purpose is front-loaded and every sentence carries distinct behavioral content, but the swap clause restates itself ('if that joins the two swap places: the backup becomes its WiFi and the old WiFi becomes the backup'). Tightening that redundancy would make it fully economical.

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 3-parameter mutation with full schema coverage, annotations, and an output schema, the description covers the remaining gaps an agent would care about: propagation delay, replacement behavior, and what happens on failover. Nothing needed to call this correctly is missing.

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

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

Schema description coverage is 100%, so ssid, password (empty for open networks), and device_id are already documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Give a screen a backup WiFi network') and implicitly distinguishes itself from the sibling host.screens.clear_wifi by making the object 'backup WiFi' explicit. An agent can tell this apart from clearing WiFi 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?

Provides clear when-to-use context — 'ahead of a network change, or while it is offline' — which is exactly the scenario an agent needs to recognize. It does not name the alternative sibling (host.screens.clear_wifi) or state when not to use it, so it stops short of full routing guidance.

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

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

Annotations declare a non-idempotent write (readOnlyHint=false, idempotentHint=false), and the description adds real behavioral context beyond them: the application is manually reviewed by Wall Marketing, then screens are shipped and the venue emailed, and no email parameter is needed because the signed-in account is used. It could still say what happens to the application after submission (editable/cancellable?) or on rejection.

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

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

The purpose is front-loaded in sentence one, which is good. However, the installation walkthrough ('connect the screen to the venue's WiFi, peel the covers off the adhesive and stick it on the wall') and the 20% revenue-share pitch do nothing to help an agent decide or invoke, padding an otherwise focused definition.

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

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

For a 10-parameter write tool with an output schema, the description covers the review-and-fulfilment workflow, the zero-cost/20%-share commercial terms, and the account-email binding. It omits post-submission lifecycle details (modifying or withdrawing an application), which is a minor gap given the output schema exists.

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

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

Schema description coverage is 100%, so all 10 parameters are already documented, including state/suburb fallback and the customers_per_day and requested_screens semantics. The description only adds 'one or more' screens and the signed-in-email implied parameter, so baseline 3 is correct.

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

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

The first sentence names a specific verb and resource ('Apply for one or more free advertising screens at a venue') and scopes the venue types. No sibling tool (host.venue.overview, host.screens.*, advertiser.venues.*) shares this apply-to-host purpose, so an agent can route to it unambiguously.

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

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

Usage is only implied: the description explains what hosting involves and that the application is tied to the signed-in account's email, which is a useful precondition. It never says when to use this versus host.venue.overview or the advertiser.venues tools, and gives no when-not guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered and the description adds content scope: screens, pending applications, earnings, withdrawals, payments and reports, plus the next offline setup window and backup WiFi. It does not state auth/account requirements, pagination, or how large a result set to expect, so it goes beyond annotations only modestly.

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 a single front-loaded sentence that opens with the scope, which is good, but the long parenthetical enumeration largely restates what an output schema already exposes. Every item is plausible payload, yet the list is dense enough to be skimmable only with effort.

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?

Because the tool aggregates many domains, the description needs to signal breadth, and it does. With zero parameters and an output schema present, the missing when-to-use routing and account/auth notes are the only real gaps.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline applies. It correctly implies the account is derived from the session rather than supplied as input.

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

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

The description names the resource precisely as 'the venues this account hosts screens at', which scopes it to the host role and separates it from advertiser.venues.get and ambassador.venues.list. The verb is implicit (an overview/aggregate read rather than a mutation), but the enumerated contents make the intent unambiguous.

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

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

There is no explicit statement of when to call this instead of siblings such as host.earnings.wallet, host.venue.apply, or advertiser.venues.get, and no prerequisites or exclusions. Usage is only inferable from the phrasing 'this account hosts screens at' and the final note about venues without screens.

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