A2A Retailmedia — the agentic retail-media hub for grocery

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds only that it returns handoff state plus a ticket, which overlaps with the existing output schema, and discloses nothing about permissions, scoping, or side effects.

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 short sentence with no padding, which is appropriately sized, but the leading phrase is front-loaded with an ambiguous action verb rather than the resource being read, hurting clarity.

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 an output schema, the description still needs to define what a 'handoff' is and when the tool should be selected over its many siblings. The jargon-heavy fragment leaves an agent unable to confidently invoke it.

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

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

There is one required parameter (handoff_id) with 0% schema description coverage, and the description never explains it. The description must compensate for the coverage gap and it does not, so an agent has no idea what form a valid handoff_id takes.

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 fragment 'Hand to a person' reads like a transfer/escalation action, but the rest of the sentence ('the state of a handoff and its Navigator desk ticket') describes a read. The intent is ambiguous and the resources named ('Navigator desk ticket', 'media program') are internal jargon that don't distinguish it from siblings like resolve_actor or get_banner_card.

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 trailing clause 'where the media program has no agent' hints at a triggering condition, but it is cryptic and gives no explicit when-to-use, when-not-to-use, or named alternative. No sibling is referenced for 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 declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: results are read live from the A2A Grocery source, implying freshness/no caching. It could say more about rate limits or failure modes when no listing exists.

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

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

Front-loaded with the core check, then the payoff, then the data source — no padding. The phrasing is metaphor-heavy ("on the shelf", "A2A Grocery door"), which is compact but slightly informal for a precise lookup tool.

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

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

An output schema exists, so return values need not be explained, and annotations carry the safety profile. What remains, the purpose and the live-data source, is stated. Format expectations for the three required identifiers are the only real gap.

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

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

Schema description coverage is 0% across three required parameters, so the description must compensate. It does map the three concepts (GTIN, banner, market≈country_iso), but gives no format guidance for any of them, leaving syntax entirely to inference.

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 concrete question ("does the grocery record list this GTIN at this banner in this market?") that precisely defines the eligibility check and its scope. It is distinguishable from siblings like resolve_gtin (identifier lookup) or find_buyer, though it never names an alternative explicitly.

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

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

The phrase "No listing, no media pitch" implies when the check matters (as a gate before pitching media), which is useful implied guidance. However there is no explicit when-to-use/when-not-to-use statement and no routing to alternatives such as resolve_gtin for pre-resolution.

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, destructiveHint=false, openWorldHint=true, non-idempotent). The description adds real value by clarifying that enrolment does not itself trigger the handoff — that waits on an approved budget — which is meaningful behavioral context. It still says nothing about permissions, duplication behavior, or the 'tick' semantics.

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

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

Two sentences with dense information: scope, required fields, and the handoff boundary condition. The 'Makers: be seen.' fragment is throwaway marketing with no operational value, but the body is efficient and front-loads the action.

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 annotations carry the mutation profile. What is missing is disambiguation of the tool's private vocabulary ('the tick', 'the 20', 'a handoff waits for a budget') and any prerequisite, which an agent needs to call this correctly alongside check_eligibility and a2a_handoff.

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 0%, so the description must carry the load. It does map all four parameters (name, markets with 'one or more of the 20', the tick/boolean, an answerable contact), but the mapping is cryptic — 'the tick' for a boolean media_exposure is not self-explanatory. Partial compensation for a total coverage gap.

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

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

States a specific verb and resource ('Enrol a maker') and its domain ('for media exposure in grocery'), which separates it from search-oriented siblings like find_makers. The distinction from a2a_handoff is also implied by 'Enrolment only — a handoff waits for a budget.' Clarity is slightly undercut by unexplained jargon ('the tick', 'the 20').

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 clause 'Enrolment only — a handoff waits for a budget a person has approved' implies this is the first step and that a2a_handoff is a later, budget-gated action. However, it never explicitly says when to call this versus check_eligibility or find_makers, so usage remains inferred rather than stated.

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

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

Annotations already declare readOnly, idempotent, closed-world, non-destructive behavior, so safety is covered. The description adds one genuine behavioral detail - that the website is returned only when the record has one - but says nothing about lookup failures, multiple matches, or what the market/decision_id inputs affect.

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. It is efficient, though the brevity contributes to the gaps elsewhere rather than being a virtue in itself.

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 annotations cover the safety profile. However, for a lookup tool with three undocumented parameters and an unexplained relationship to find_makers, the description is thinner than the complexity warrants.

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 0% across three parameters, so the description carries the full burden. It only implies the 'maker' name lookup ('by name') and never explains 'market' or 'decision_id', leaving two of three inputs entirely undefined.

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 concrete action (look up a maker by name on the grocery record), but the name/title say 'buyer' while the body says 'maker', and it never distinguishes itself from the very similarly named sibling find_makers. The mismatch and lack of sibling differentiation leave the agent guessing which tool to pick.

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

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

The only usage framing is the terse 'Qualify the buyer', with no when-to-use, no prerequisites, and no mention of alternatives such as find_makers or resolve_actor. An agent gets no signal about when this tool is preferred over its near-duplicate sibling.

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, idempotentHint, destructiveHint=false and closed-world, covering the safety profile. The description adds one piece of context beyond that — data is read live from the A2A Grocery door (not cached) — but says nothing about the return shape or any access constraints. Annotations carry most of the burden, so a 3 is appropriate.

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 with no padding, and the core action is front-loaded before the node and segment qualifiers. The phrasing is terse to the point of being cryptic ('lane where it names one'), 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?

For a 4-parameter tool with 0% schema coverage, two parameters (limit, region) are explained nowhere, and there is no usage or filtering guidance. The output schema covers return values and annotations cover safety, but the input-side gaps leave the description incomplete for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It usefully explains node (one of 20 markets) and enumerates segment values (organic, free-from, plant-based, artisan, origin, premium) that the schema does not, but it never mentions limit or region, leaving half the parameters undocumented anywhere.

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: finding brand makers on the grocery records of one market. The parenthetical 'node = one of the 20 markets' clarifies scope, and 'makers' implicitly contrasts with the sibling find_buyer. Slightly jargon-heavy wording ('brand: makers', 'grocery record') keeps it from a clean 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?

No explicit when-to-use or when-not guidance, and no routing to alternatives such as find_buyer or the enrol/resolve siblings. The segment sentence is parameter semantics rather than usage context, so the agent is left to infer when this is the right 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 disclose that this is a non-readonly, non-idempotent, open-world call, so the safety profile is covered. The description adds genuinely non-structured behavior: a decision_id is returned and consumed by handshake tools, and a deny incurs no charge — a billing rule an agent cannot derive from annotations. It still omits auth requirements and whether repeated calls are safe.

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

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

Three short sentences with the gating purpose front-loaded, followed by the return contract and the billing rule. No filler, no repetition of the title or schema.

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

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

An output schema exists, so the description need not detail return values beyond the decision_id hint, and annotations cover the mutation profile. Still missing for a billing-relevant decision gate: prerequisites (resolving market/actor identifiers), the consequence of a deny beyond billing, and whether repeat calls create duplicate decisions.

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 0% with two required, undescribed parameters, so the description carries the full burden. "One market and one actor class" only restates the property names and clarifies cardinality (singular), giving no format, code system, or resolution guidance despite siblings like resolve_jurisdiction and resolve_actor suggesting these values must be resolved first.

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

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

States a concrete verb and resource: it issues an allow/deny decision for one market and one actor class, and identifies itself as the pre-handshake gate that emits a decision_id. It stops short of distinguishing itself from the close sibling check_eligibility, which an agent would plausibly confuse with a gating decision.

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 gate before a handshake" implies the correct ordering (call this before handshake tools), which is real sequencing guidance. However there is no explicit when-not guidance and no mention of check_eligibility or a2a_handoff as alternatives, so the agent must infer which sibling owns an eligibility question.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds useful behavioral context — the card is 'signed' and the status vocabulary is enumerated (listed · claimed · verified) — but says nothing about caching, auth requirements, or failure modes when a banner slug is unknown.

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 core purpose front-loaded and the parameter hint appended. No filler, no 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 return shape needn't be explained, and annotations carry the safety profile. However, with a required 'market' parameter undocumented and no routing guidance against list_banner_cards, the agent is left to guess on a required input.

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 0%, so the description must compensate. It does so for 'banner' by listing accepted identifier forms (slug, id or name), which is genuinely useful, but the required 'market' parameter is left completely undocumented in both schema and description.

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

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

The description names a specific resource (the signed card of one banner) and its scope (single banner, plus status), which distinguishes it from the plural sibling list_banner_cards. The retrieval verb is only implied by the noun phrase rather than stated, but the singular/plural contrast makes 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 when-to-use or when-not-to-use guidance. The agent must infer from singular vs. plural that this fetches one card and list_banner_cards fetches many; no prerequisites or alternatives are named.

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, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds the requested status vocabulary and hints at the shape of each card, but says nothing about pagination behavior, result ordering, or the market/status interaction beyond what a read-only list implies.

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 compact sentence with no filler, and the market scope is front-loaded ahead of the optional status filter. The colon-list of fields is dense but readable; only the missing leading verb keeps it from being perfectly structured.

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

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

With an output schema present, the description need not explain return values, so its field list is bonus context. It still leaves an agent guessing about pagination (limit/offset defaults) and about how this differs operationally from get_banner_card, which is a notable gap for a four-parameter list 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 0%, so the description must compensate. It does add real meaning for 'market' (one market) and supplies the three 'status' values that the schema's bare anyOf string lacks, but limit and offset are completely unexplained by either source.

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

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

The description names the resource ('the cards of one market') and the returned fields (banner, media program, status, address), which clearly separates it from the singular sibling get_banner_card. It is a noun phrase rather than a verb-led statement, so the listing action is only implied by the tool name, but the scope is unambiguous.

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

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

'optionally by status (unclaimed, claimed, registered)' implies the filtering use case, and 'one market' implies the required scoping. However, it never states when to pick this over get_banner_card or list_banners, nor any prerequisites or exclusions, so usage is only inferred.

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

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

Annotations already declare this a safe, idempotent, non-destructive, closed read, so the safety profile is fully covered elsewhere. The description usefully adds that a banner without a program shows 'none listed' and that with_program filters on that, but it says nothing about pagination behavior or the meaning of limit/offset.

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

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

Two sentences, no obvious fluff, and the filter rule is placed at the end where it is easy to miss. The run-on phrasing of the first sentence ('Pick the banners: the grocery banners of...') is awkward and slightly obscures the core action.

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

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

An output schema exists, so return values need not be spelled out, and annotations cover safety. However, for a 5-parameter tool with zero schema coverage, leaving three parameters unexplained means the definition is not quite complete enough for an agent to call it fully correctly.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It clarifies 'market' and 'with_program' but leaves limit, offset, and search entirely undocumented in both schema and description, which is a substantial gap for a 5-parameter tool.

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

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

States a specific verb (list/pick) and resource (grocery banners of one market), plus what each entry carries (media program, card status). It does not distinguish itself from sibling list_banner_cards or get_banner_card, so it falls short of full sibling differentiation.

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

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

The description gives one concrete usage rule: setting with_program=true returns only banners that have a program listed. Beyond that there is no guidance on when to choose this over list_banner_cards or get_banner_card, and no prerequisites 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 declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuine domain semantics beyond that: the onsite/offsite/in-store tagging and the rule that offsite entries are never shelf slots, plus the empty-result stopping behavior. It adds nothing on auth needs or result shape (output schema exists), so a 3 is right.

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, so size is not the problem, and the action is placed first. However, the vocabulary ('shelf slot', 'in the program's own words') is opaque and the offsite-tagging sentence reads as niche trivia rather than load-bearing instruction.

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

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

For a read-only lookup this is under-specified: two of three parameters are undocumented with zero schema coverage, there is no guidance on when to call it versus quote_package/renew_package, and the purpose verb is ambiguous. The presence of an output schema excuses it from explaining return values, but not from the remaining 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?

Schema description coverage is 0% for all three parameters. The phrase 'what one banner's media program says' loosely gestures at the banner parameter, but market and decision_id are never mentioned or explained anywhere in the description, so it fails to compensate for the total schema gap.

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

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

The description names the resource (a package = a banner's media program offering) and implies a lookup/match behavior, but the verb 'Match' conflicts with the name/title 'List Packages' and it never states plainly that it returns a list for a banner/market. No sibling is named or excluded, so an agent cannot distinguish it from quote_package or renew_package without opening the 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?

There is no when-to-use statement and no alternatives offered. The only procedural note — 'Empty where no program is listed — the agent stops' — describes a termination condition for the calling loop, not the conditions that select this tool over its siblings.

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

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

Annotations already declare the write profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true), so the safety picture is covered. The description is consistent with them but adds only 'returns its id', which duplicates the existing output schema. No mention of rate limits, ordering guarantees, or failure behavior.

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

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

A single front-loaded clause with zero filler. It is efficient, though arguably terse to the point of under-specification rather than deliberately concise.

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

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

An output schema exists so return values need no explanation, and the tool is simple (2 params, 1 required). Still, the undefined 'chain' concept and entirely undocumented parameters leave gaps for an agent deciding what to pass.

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 0%, so the description carries the full burden for 'event' and 'detail'. It never explains what an event string should contain or how 'detail' differs, leaving both parameters semantically opaque.

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 (write) and resource (one audit line) and names a scope that no sibling tool covers, so an agent can tell it apart from transaction/package tools. The phrase 'a step of the chain' is undefined domain jargon, 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives among the 19 sibling tools. The agent must infer that this is the trailing audit call after some other operation.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds only the availability precondition; it does not explain the reliance on a retailer program, what happens if the program has not returned, or any failure modes.

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 precondition is stated plainly. The opening metaphor ('Read the till') costs a little clarity for the sake of brevity, but the text is appropriately sized for a one-parameter read tool.

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

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

An output schema exists, so return values need not be described, and the single parameter is the only structural gap. Still, a thin one-parameter tool with a prerequisite should make the dependency on the handoff flow and the jargon 'till' unambiguous, which it only partially does.

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 0% for the single required parameter handoff_id, so the schema contributes nothing. The description's reference to a 'campaign id for a handoff' only loosely implies where handoff_id comes from, without stating that handoff_id is the id issued by the prior handoff and how to obtain it.

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 retrieval verb ('Read') and a resource ('results of a campaign'), but the framing 'Read the till' is idiosyncratic jargon that is not explained, and it never distinguishes this tool from siblings like a2a_handoff or gate_transaction. An agent gets the gist (fetch campaign measurement results) but not a precise contract.

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 one explicit precondition — available only after the program returns a campaign id for a handoff — which is genuinely useful sequencing information. However, no alternatives are named and there is no when-not-to-use guidance, so the agent still has to infer when this tool is preferred over a2a_handoff or check_eligibility.

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, idempotentHint=true, openWorldHint=false and non-destructive, so the safety profile is covered. The description adds a genuinely useful behavioral fact — that the tool does not compute a price but points to where rates are published/enquiries are taken — which is context beyond the annotations. It stops short of describing what the returned quote source looks like or any auth/rate constraints.

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 point is reasonably front-loaded. The clipped 'Price it:' opener is punchy but slightly at odds with the need for precision in an agent-facing 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?

An output schema exists and annotations cover the safety profile, so return-format explanation is not required. The remaining gap is parameter meaning: three undocumented inputs with 0% schema coverage leave the agent guessing what market and decision_id should contain, which is material for correct invocation.

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

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

Schema description coverage is 0% for three parameters (banner, market, decision_id), so the description carries the full burden and largely fails it. Only 'banner' is obliquely referenced via 'the banner's own media program'; market and decision_id receive no explanation at all. With sub-50% coverage the description should compensate but does not.

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

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

The description states a domain-specific purpose: returning where the banner's media program publishes rates or takes an enquiry, and clarifies that GSC itself never prices. However, the framing ('Price it:') is cryptic and the actual verb+resource ('returns a quote source') is only inferable, not stated plainly. It does implicitly separate this from pricing/renewal siblings but without naming them.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The statement 'GSC never prices; a quote comes from the retailer's program' explains the domain model but does not tell the agent when to call quote_package versus list_packages, submit_demand, or renew_package. Usage is left entirely to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, covering the safety profile. The description adds that only a registered card can receive and that others are refused without charge, which is useful state-dependent behavior. However, with an output schema present, it need not explain returns, and it omits other behavioral details like error handling or side effects.

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the retailer-side role and the card-state condition.

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

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

Although an output schema exists, the description fails to describe any of the four parameters, offers no guidance on when to use the tool versus its many siblings, and provides only minimal behavioral context. For a tool with required handoff_id and decision_id at 0% schema coverage, this is inadequate.

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 0%, and the description does not describe any of the four parameters. It does not clarify what 'market', 'banner', 'handoff_id', or 'decision_id' mean or how they should be supplied, leaving the agent with no semantic guidance from the description.

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

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

The description states it is a retailer-side operation where an agent receives a demand packet, which gives a general sense of the action. However, compared to siblings like submit_demand or a2a_handoff, the description does not clearly distinguish what uniquely happens here or what the handoff_id/decision_id represent, leaving the purpose only vaguely 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?

There is no explicit guidance on when to use receive_demand versus submit_demand or a2a_handoff, nor are prerequisites beyond the registered-card state mentioned. The description implies the card must be in a registered state but does not tell the agent under what circumstances to call this 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 this is a non-read-only, non-idempotent, open-world, non-destructive write, so the mutation profile is covered. The description adds the prior-quote-id precondition, which is real behavioral context, but says nothing about permissions (the budget_approved_by parameter hints at an approver requirement without explaining it) or side effects. With annotations carrying safety, a 3 is appropriate.

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 the operative verb 'Renew' front-loaded and zero filler. The first sentence is telegraphic ('Renew: a prior quote id ... and a new approved budget'), which slightly hurts readability but keeps it tight.

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

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

An output schema exists, so return values need not be described, and the precondition is stated. Still, for a mutation tool the description leaves the optional decision_id unexplained and gives no indication of how this differs from the closely-named quote_package sibling, so it is only minimally 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 0%, so the description must compensate and only partially does: it maps prior_quote_id and budget (the 'new approved budget'). budget_approved_by and decision_id are never mentioned, and decision_id being nullable with a default is left entirely unexplained. Two of four parameters remain undocumented in both schema and description.

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

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

The description states the verb 'Renew' and hints at the resource by tying it to a prior quote id and a new approved budget, so an agent can tell roughly what happens. However it never names the resource being renewed (package/quote) and offers no differentiation from siblings like quote_package or list_packages. Purpose is inferable but not crisp.

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 a precondition — 'Without a quote id from the program there is nothing to renew' — which implies when this tool is applicable versus when it is not. It does not, however, contrast the tool against alternatives such as quote_package or gate_transaction, so usage guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds domain context beyond that: auditor is read-only and the consumer is never the counterparty, which is useful behavioral framing but limited in scope.

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?

Extremely short and front-loaded with the core question, with no wasted sentences. It is slightly cryptic in phrasing, but every clause (class list, auditor note, consumer exclusion) 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?

With an output schema present, return values need not be explained, and the description supplies the missing value set for the single parameter. Still missing is any statement of when the tool is invoked or its place relative to the many sibling tools, leaving the definition minimally adequate.

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 0% and actor_class has no enum, so the schema provides almost nothing. The description compensates by enumerating the valid values (maker, brand_owner, agency, distributor, retailer_media_team, auditor), which materially improves correct invocation.

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

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

The description opens with 'Who is asking?' and enumerates actor classes, which implies the tool determines the caller's actor identity. However, it never states a clear verb+resource ('resolve actor' is only in the name), and it does not distinguish itself from siblings like check_eligibility or gate_transaction. Purpose is inferable but vague.

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 guidance, no prerequisites, and no named alternatives among the many sibling tools. The parenthetical 'auditor (read only)' hints at a usage condition but does not tell the agent when this tool should be selected versus others.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful provenance details beyond annotations: the record is signed, comes from gtinfetch.ai, and is read live from the A2A Grocery door. It does not cover auth requirements or rate limits.

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

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

The description is fairly compact, but the opening clause 'hub layer: seat, market, claim, price, availability' is cryptic and not explained. The core purpose is present but not front-loaded with maximum clarity.

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 safety. However, the single input parameter remains underspecified, and the description's jargon around hubs, seats, markets, claims, and prices is not grounded enough for an agent to fully understand the result context.

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

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

The schema has 0% description coverage for the single gtin parameter, so the description must compensate. It expands GTIN and says the tool checks whether it is well-formed, but it does not specify accepted formats, checksum rules, or examples.

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

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

The description states a specific action: confirm whether a GTIN is well-formed and exists on the grocery record with brand and maker. It names the resource and outcome clearly, though it does not differentiate this tool from sibling resolve_* or lookup tools.

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

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

The phrase 'Confirm the product is real' implies the tool's use case, but there is no explicit guidance on when to choose this over alternatives or when not to use it. Usage is inferable rather than stated.

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

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

Annotations already declare this as a safe, idempotent, non-destructive, non-open-world lookup. The description adds genuinely useful behavior beyond that: the result is constrained to a fixed set of 20 canonical markets, and input aliases are handled ('UK is the label; GB is accepted'). This normalization rule is exactly the kind of quirk an agent cannot get from annotations or schema.

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

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

Three short sentences, front-loaded with context then the directive, with no filler. The opening question is slightly rhetorical but earns its place by setting domain context cheaply.

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 structure need not be spelled out, and the description still notes the output is one of 20 canonical markets. Input format, examples, and alias behavior are all covered; only explicit when-to-use guidance 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 0%, so the description carries the full burden for the single 'market' parameter. It supplies valid examples and an explicit alias rule (UK label, GB accepted), which materially compensates for the undocumented 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 (Resolve) and resource (a market/jurisdiction), with concrete input examples (FR, UK, US, Japan) and a stated output domain (one of the 20 markets on the record). It does not explicitly distinguish itself from sibling resolvers like resolve_actor or resolve_gtin, but the resource noun makes the difference inferable.

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 framing question 'Where is the media bought?' implies the context in which this normalization is needed, but there is no explicit when-to-use, no prerequisite, and no routing to alternatives. Usage is implied rather than stated.

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

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

The routing rule (unclaimed=referral, claimed=retailer media team, registered=agent-to-agent) is real behavioral context beyond the annotations, which only declare it is a non-readOnly, openWorld write. However, the description leaves permission/auth requirements opaque and 'Settles at the door' conveys nothing actionable.

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 dense sentences that are front-loaded starting with the intent, but the flowery wording ('the packet', 'Settles at the door') consumes space without adding callable meaning.

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, but for a 7-required-parameter write tool the description omits key parameters and any auth/precondition context, and its colorful closing image is opaque rather than informative.

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 0%, so the description carries the full param burden. It maps well to six of the nine (maker, budget, budget_approved_by via 'a budget a person has approved', gtins, market, banners) but never mentions contact, note, or decision_id, leaving required 'contact' undocumented anywhere.

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 payload (maker, approved budget, GTINs, market, banners) and the routing behavior, so the agent can infer this submits a demand. However, the framing verb 'Hand off' and phrases like 'Settles at the door' are cryptic and it never distinguishes itself from close siblings such as a2a_handoff or receive_demand.

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 or when-not-to-use guidance and no named alternative, despite several plausible routing siblings. The clause 'or a gap naming what is missing' hints at a failure mode but not at when the agent should reach for this tool over the others.

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