A2A Retailmedia — the agentic retail-media hub for grocery

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

The description says 'Hand to a person,' which implies a state-changing action, while annotations declare readOnlyHint=true. This is a direct contradiction. No other behavioral context (auth, rate limits) is provided.

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 sentence, but it is convoluted, ambiguous, and not front-loaded with a clear purpose. The structure hinders rather than aids comprehension.

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, but the description fails to identify the tool's operation or the parameter, leaving 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?

Schema description coverage is 0% and the sole parameter handoff_id has no description in either the schema or the tool description. The description does not mention the parameter at all, leaving its meaning entirely undocumented.

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 does not clearly state a verb+resource. 'Hand to a person' suggests an action (handoff) while the rest describes retrieving state, making the tool's purpose ambiguous and difficult to distinguish from siblings.

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

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

Only a fragment of a condition ('where the media program has no agent') implies when it applies, but there is no explicit when/when-not guidance or mention of alternatives.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds 'Read live from the CPG Knowledge Graph door', indicating fresh live data rather than a cache, which is genuine extra context but shallow.

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 question front-loaded, followed by exclusions and the data-source note. The metaphorical phrasing ('on the shelf', 'door') is flavor rather than wasteful, but not fully austere.

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

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

With an output schema present, return values need no explanation, and annotations cover the safety profile. What remains is a slightly under-specified notion of what 'eligible' resolves to, but the essentials for calling a 3-param read tool are 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?

Schema coverage is 0%, so the description must compensate. It informally names all three concepts (GTIN, banner, market ≈ country_iso), giving partial mapping, but supplies no format or syntax for the codes and never explicitly ties 'market' to country_iso.

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 check — eligibility of a GTIN at a banner in a market — and explicitly contrasts it against adjacent work ('No listing, no media pitch'). It reads as a read-only eligibility probe. The metaphor ('on the shelf', 'Knowledge Graph door') and lack of explicit differentiation from resolve_gtin keep it from 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?

'No listing, no media pitch' tells the agent what this tool is not for, which is useful negative guidance. However, it never states when to reach for check_eligibility over resolve_gtin or get_banner_card, leaving the choice 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 this is a write (readOnlyHint=false), non-idempotent, non-destructive, open-world operation, so the safety profile is covered. The description adds a genuine workflow constraint — that this only enrols and a handoff requires human-approved budget — but says nothing about duplicate handling, permissions, 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?

Two sentences, front-loaded with the action, which is good. But the opening 'Makers: be seen.' is marketing filler that does not help an agent decide or invoke, and the second sentence mixes param listing with workflow caveats.

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. Still, for a 4-required-parameter write tool with 0% schema coverage, the description leaves key details thin: the boolean 'tick' mapping is unclear and there is no guidance on market identifiers or contact format.

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 load. It does map all four parameters to human terms ('its name', 'its markets (one or more of the 20)', 'the tick', 'a contact a person can answer') and adds the useful constraint of 20 selectable markets. But 'the tick' is opaque for the media_exposure boolean, leaving a real 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 states a specific verb and resource: 'Enrol a maker for media exposure in grocery', which is distinguishable from siblings like find_makers (search) and a2a_handoff (handoff). However, jargon such as 'the tick' and 'be seen' slightly obscures exactly what is happening, and 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?

'Enrolment only — a handoff waits for a budget a person has approved' implies the boundary versus a2a_handoff, giving the agent a sense of when this tool stops and another begins. It does not, however, name the alternative tool or state preconditions for using this one (e.g., eligibility checks), so usage is only implied.

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. The only added behavioral detail is the conditional 'with its own website where the record has one', which is minor; no auth, rate-limit, or lookup-failure behavior is disclosed.

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

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

A single tight sentence with the action front-loaded and no filler. Its brevity is fine; the shortfall is substance, not length.

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

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

An output schema exists so return values need not be described, but with 3 parameters at 0% coverage, no usage routing, and a name/resource mismatch, the definition leaves an agent under-equipped to invoke this 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%, and the description only gestures at the 'maker'/'by name' parameter. It says nothing about 'market' or 'decision_id', leaving two of three parameters undocumented in both schema and prose.

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 verb and a resource ('find a maker on the grocery record by name'), but the resource conflicts with the tool name/title ('find_buyer' / 'Find Buyer'). It also reads nearly identically to the sibling 'find_makers', so an agent cannot confidently tell the two apart from the text.

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 'Qualify the buyer' hints at intent but gives no when-to-use condition, no prerequisites, and no comparison to the obvious alternative 'find_makers'. Nothing tells the agent when this tool is the right choice 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 readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The phrase 'Read live from the CPG Knowledge Graph door' adds that results come from a live graph read rather than a cache, which is genuine extra context, but nothing is said about result shape, pagination, or empty-result 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?

Two short sentences with no filler, and the filter dimensions are stated up front. The only waste is the decorative 'CPG Knowledge Graph door' phrasing.

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, but with 0% schema coverage on four parameters and no usage routing, an agent cannot confidently construct a call or know when this tool beats find_buyer.

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 all four parameters. It loosely covers segment and region (and mentions 'market', which is not even a parameter), but leaves 'node' and 'limit' entirely unexplained 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?

States a verb (Find) and resource (makers/brand makers) plus filter dimensions (segment, region, market), which is enough to separate it from find_buyer at a glance. However, 'on the consumer goods record' and 'the CPG Knowledge Graph door' are cryptic framing rather than specifics, and no sibling is named for 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 no when-to-use guidance, no prerequisites, and no pointer to alternatives such as find_buyer, resolve_actor, or resolve_gtin. An agent must guess which discovery tool fits a given query.

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

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

Annotations already flag this as a non-readOnly, open-world, non-idempotent, non-destructive operation. The description adds genuinely useful behavior beyond them: it emits a decision_id consumed by downstream handshake tools, and it discloses the billing rule that "a deny is not charged." It stops short of explaining the non-idempotent side effect (what calling twice does).

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 zero filler, and the core allow/deny purpose is front-loaded before the return value and billing caveat. Nothing needs trimming.

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 enumerated, and the description still notes decision_id for chaining. Parameter semantics and the deny billing rule are covered for a simple two-param tool; only format-level parameter detail and any auth/rate context are absent.

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

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

Schema description coverage is 0%, so the description carries the burden, and it does name the semantics of both parameters: one market and one actor class per call. However it gives no format, vocabulary, or validation guidance (e.g., what identifiers markets or actor classes take), so ambiguity remains at invocation time.

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: gate a transaction with an allow/deny decision scoped to one market and one actor class. It's clearly a pre-handshake decision point. It doesn't, however, distinguish itself from the similar-sounding sibling check_eligibility, leaving ambiguity about which gating 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 gate before a handshake" implies the ordering context, and naming handshake tools as the consumers of the returned decision_id suggests when it's needed. But no alternative is named or excluded, and check_eligibility is a close sibling that the description never contrasts against.

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 the safety profile is covered. The description adds the status domain (unclaimed/claimed/registered), which is useful behavioral context, but with an output schema present that state information may already be documented there. No mention of auth, rate limits, or error 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?

Two short sentences with no filler, and the return-state enumeration is front-loaded before the parameter hint. It is appropriately sized, though the telegraphic 'banner = ...' style slightly undercuts readability.

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 two-required-parameter lookup the description covers the 'banner' accepted-format question well and the output schema handles return values. The gap is 'market': an agent has no idea what value format or scope that required parameter needs, which is a meaningful omission for a fully required-input 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 carry the load. It usefully explains that 'banner' accepts a slug, id, or name, which is genuinely beyond the bare string type in the schema. However, the required 'market' parameter is left completely unexplained in both places, leaving half the inputs undocumented.

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 ('the signed card of one banner and its status') and enumerates the possible states, which clearly separates it from the plural sibling list_banner_cards. The verb is only implied by the name 'get', but the scope of the returned artifact 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?

The phrase 'one banner' hints that this is the single-item counterpart to list_banner_cards, but there is no explicit when-to-use statement, no prerequisite (e.g., resolving a slug/id first), and no named alternative. An agent must infer the routing from the singular/plural names alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds the meaningful detail that results are scoped to one market and that status values are unclaimed/claimed/registered (values absent from the schema), but says nothing about ordering, paging, or return volume.

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-scoping constraint plus optional filter come first. The trailing colon-list of returned fields makes the tail slightly harder to parse, but it is efficient overall.

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

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

An output schema exists, so return fields need not be enumerated (and partly duplicating them adds little), and annotations cover safety. However, for a 4-parameter list tool it leaves pagination and tool-selection guidance unaddressed, which an agent would need.

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 parameter meaning, and it covers only market and status — and its status values are genuinely additive since the schema's status field is a bare anyOf string/null with no enum. It is completely silent on limit and offset, leaving pagination behavior undocumented, so it only partially compensates.

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 identifies the resource (banner cards) and scopes it to a single market with an optional status filter, so an agent can tell it lists cards rather than fetching one. It does not explicitly contrast itself with siblings like get_banner_card or list_banners, so sibling differentiation is left to the name.

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 notes that status filtering is optional, which hints at one usage mode, but there is no statement of when to prefer this tool over get_banner_card or list_banners, and no prerequisites or exclusions. The agent must infer routing from the tool name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is covered. The description adds a genuine behavioral detail — that a missing program renders as 'none listed' rather than being omitted — which is useful beyond the annotations, but says nothing about paging behavior or result size.

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 resource and return shape front-loaded; the filter rule follows. Phrasing like 'Pick the banners' is slightly informal, but nothing is 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 not be spelled out, but the description does not compensate for 0% schema coverage on limit/offset/search. For a 5-parameter listing tool, an agent is left guessing what search matches and how paging behaves.

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 only one of five parameters is addressed: with_program. Market is implied by 'of one market', but limit, offset and especially search (an anyOf string/null with default null) are left entirely unexplained 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?

States a concrete verb+resource: grocery banners of one market, plus what each row carries (media program, card status). An agent can separate it from get_banner_card/list_banner_cards by the plural 'banners of a market' scope, though the description never explicitly contrasts 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?

It gives one selection rule — with_program=true narrows to banners with a listed program — which implies the default lists everything. But there is no guidance on when to use this vs. get_banner_card (single banner) or list_banner_cards, and no prerequisites or exclusions.

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

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so safety is covered. The description adds real behavioral value beyond that: it explains the onsite/offsite/in-store tag scheme, the rule that offsite must never be treated as a shelf slot, that values are verbatim from the program, and that empty results should halt the agent.

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 little filler, but the structure is fragmentary and telegraphic ('Match a package: what one banner's media program says it sells'), which costs clarity. Key scoping information is not front-loaded.

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

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

An output schema exists, so return values need not be described, and the annotations cover the safety profile. What remains missing is parameter semantics for a tool with two required inputs, which is the primary contextual gap for a list/retrieval tool in this domain.

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 parameter meaning, but it names no parameters at all. It only implies banner scoping ('one banner's media program'); 'market' and the optional 'decision_id' are entirely unexplained.

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 conveys that it retrieves what a banner's media program sells (packages) and how they're tagged, but the opening verb is 'Match a package' rather than 'list', leaving the actual operation ambiguous. It never distinguishes itself from siblings like quote_package or renew_package that operate on the same package concept.

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 when-to-use guidance and no named alternatives against a large sibling set. The only usage-adjacent statement is the empty-result rule ('Empty where no program is listed — the agent stops'), which describes a downstream behavior rather than when 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 readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the write profile is covered structurally. The description adds that exactly one line is written and that an id is returned, which is useful, but with an output schema present the return-value note is redundant and it says nothing about auth needs or duplicate-line behavior implied by non-idempotence.

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 tight sentence with the action front-loaded and no filler. Every clause carries information, though the return-value clause is arguably redundant given the output 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?

The existence of an output schema excuses omitting return details, but with 0% schema coverage on parameters the description leaves the agent without any guidance on what to supply for `event` or `detail`. Combined with absent usage guidance, this is incomplete for a two-parameter write 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 carry the burden for two parameters, yet it never names or explains `event` or `detail`. 'One audit line' gestures at the payload but does not differentiate the required event from the optional detail or indicate accepted formats.

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: 'Write one audit line for a step of the chain.' This is clearly a mutation that appends an audit record, and no sibling tool competes for that role. It stops short of 5 only because 'step of the chain' is domain jargon left undefined.

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 'for a step of the chain' hints at context but gives no explicit when-to-use guidance, no prerequisites, and no alternatives among the 19 sibling tools. Nothing tells the agent when this call is appropriate versus other logging or handoff tools.

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 fully covered structurally. The description's only added behavioral fact is the post-handoff availability constraint; it says nothing about latency, partial results, or what an empty measurement set means.

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 core purpose front-loaded and the gating condition immediately after. The only waste is the 'read the till' metaphor, which costs a few words without adding 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 here, and with one parameter plus full safety annotations the surface is small. The remaining gap is how an agent obtains a valid handoff_id, which the description gestures at but does not close.

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 handoff_id, so the description must carry the load and largely does not. It mentions a 'campaign id for a handoff' rather than handoff_id itself, which hints at the workflow origin of the value but never clarifies the identifier's source, format, or relationship to the campaign id.

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 clear verb+resource: read/pull campaign results returned by the retailer's program, which is distinguishable from sibling tools like quote_package or gate_transaction. The 'read the till' metaphor is colorful but adds ambiguity rather than precision, and no sibling is named explicitly to route the agent.

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

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

Gives an unambiguous precondition: only callable after the program returns a campaign id for a handoff. That is clear context for when the tool is valid, but it names no alternative and does not say what to do if the handoff has not completed.

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 does add one genuinely useful behavioral fact beyond the annotations: the tool does not compute a price but returns a publication/enquiry location. However, with an output schema present, the return-value clarification is partly redundant, so this lands at an adequate 3.

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 short — two sentences — but not well structured: the leading imperative contradicts the sentence that follows it, and the agent must resolve the negation before understanding the tool. Low word count, poor front-loading.

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

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

The output schema covers return values and the annotations cover safety, but for a three-parameter tool with zero schema descriptions, the entry point for the two required parameters (banner, market) and decision_id is left unexplained. Combined with no usage routing, an agent cannot reliably construct a correct call from this description alone.

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 (banner, market, decision_id), so the description carries the full burden — and it fails. It alludes to the banner's program but never explains what "market" means here (geo? currency? channel?) or what decision_id is for, and decision_id is not mentioned at all. The description does not compensate for the 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?

The description does convey a specific outcome — it returns where the banner's media program publishes rates or takes an enquiry — but it opens with the misleading imperative "Price it" and then immediately negates it ("GSC never prices"). The framing is jargon-heavy ("banner", "GSC", "program") and the agent must reconstruct that this is a routing/lookup tool rather than a pricing tool. It is vaguely rather than precisely stated.

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

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

There is no when-to-use guidance relative to the many plausible siblings (check_eligibility, list_packages, gate_transaction, submit_demand). It only distinguishes against GSC, which is not a sibling tool in the list. The agent gets no signal about which of the 18 other tools should precede or follow this one.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is largely covered. The description adds a genuine behavioral fact beyond annotations: refusal behavior for non-registered cards and the guarantee that 'nothing is charged' on refusal. It still omits return semantics and side effects on success.

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 tightly written sentences, front-loaded with the actor and the key constraint. Little waste, though the jargon-heavy phrasing slightly reduces immediate 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, but with four undocumented parameters at 0% schema coverage and no explanation of the handoff/decision semantics, the definition is not complete enough for an agent to call the tool correctly. The mutation nature of the tool is also only thinly characterized.

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 of explaining parameters, yet it mentions none of the four (market, banner, handoff_id, decision_id). It neither explains what a 'handoff_id' or 'decision_id' is nor the null default on decision_id, leaving all parameters undocumented.

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 actor (retailer-side registered program agent) and the action ('takes a qualified packet'), giving a rough sense of purpose. However, it relies on heavy domain jargon ('qualified packet') and never distinguishes this from the sibling submit_demand, so an agent could easily confuse the two. Purpose is implied rather than stated with a clear verb+resource.

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 state precondition ('only a card in the registered state can receive'), which is useful implied-usage context. But it offers no when-to-use/when-not guidance and never names an alternative (e.g., submit_demand) to route the agent correctly between the two demand tools.

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 provide key behavioral traits (not read-only, open-world, non-idempotent, not destructive). The description adds that renewal requires a prior quote id and an approved budget, which clarifies a precondition. However, it doesn't explain side effects, permission requirements, or what happens to the original quote. It goes beyond annotations slightly but misses deeper behavioral context.

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

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

The description is very concise, using two short sentences. It front-loads the key requirement (quote id and budget) and the consequence of missing a quote id. It is efficient, though the phrasing is somewhat terse and could be slightly clearer without losing brevity.

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

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

Given four parameters (three required), no parameter descriptions, and an existing output schema, the description covers the essential precondition (quote id) but does not address the roles of budget, budget_approved_by, or decision_id. It provides enough context to understand the core dependency but leaves the agent needing to infer details from the schema alone.

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%, meaning the description must compensate. It explains that prior_quote_id comes from the retailer's program and that budget must be approved, adding meaning to two of four parameters. However, it does not clarify decision_id (optional) or the format of budget_approved_by, leaving gaps for those 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?

The name and title state 'Renew Package' and the description implies renewing a quote to a new budget. However, the description is abstract and doesn't clearly define what a 'package' is or how this tool differs from siblings like quote_package or list_packages. The purpose is inferable but not explicitly stated in a specific verb+resource form.

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 says a quote id is required, which hints at a prerequisite, but it doesn't specify when to use this tool versus alternatives such as quote_package (new quote) or list_packages. There is no explicit when-to-use or when-not-to-use guidance, leaving the agent to infer context from the name and dependency alone.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds a genuine semantic constraint — 'the consumer is never the counterparty' — and flags auditor as read-only, consistent with the annotations. It does not disclose auth requirements or what happens on an unrecognized actor, so it goes only modestly beyond the structured fields.

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

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

Very compact and front-loaded with the value list, with no filler sentences. The fragmentary grammar ('Who is asking? maker, ...') is terse to the point of being slightly cryptic, 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?

An output schema exists, so return values need not be explained, and the actor-class enumeration covers the input domain. However, for an identity-resolution tool the description omits when resolution is required, what happens for an unrecognized or unauthenticated caller, and how it relates to the resolve_* siblings, leaving 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 schema has one parameter (actor_class) with 0% description coverage and no enum, so the description carries the full burden — and it effectively supplies the value set: maker, brand_owner, agency, distributor, retailer_media_team, auditor. It does not name the parameter or explain format constraints, but the enumeration substantially compensates for the 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 name 'resolve_actor' plus the enumeration of actor classes implies the tool identifies the calling party's role, but the description never states the verb or the resource explicitly — 'Who is asking?' is a rhetorical question, not a purpose statement. It does not distinguish itself from the sibling resolve_* tools (resolve_gtin, resolve_jurisdiction), which an agent must differentiate.

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 alternative tool is named. The parenthetical '(read only)' on auditor hints at a read-only path but does not tell the agent when to call this versus check_eligibility or a2a_handoff.

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=true, idempotent=true, destructive=false, closed-world, so the safety profile is covered. The description adds only that resolution happens against a 'CPG Knowledge Graph door' and that success implies the product is real; it says nothing about failure behavior, missing GTINs, or lookup 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?

A single front-loaded sentence that states the verb, resource and purpose with no filler. The slightly colloquial 'Knowledge Graph door' is the only soft spot in an otherwise tight formulation.

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 and full annotation coverage, the description supplies what an agent needs to select and call it. Only the absence of failure-case context (what an unresolved GTIN means) keeps it from being fully 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 carry the parameter burden. It does expand the acronym to 'Global Trade Item Number' and identifies it as a product identifier, which adds real meaning, but it supplies no format guidance (digit count, checksum, accepted variants).

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 and resource ('resolve a Global Trade Item Number') plus an outcome ('Confirm the product is real'), which is clearer than a bare restatement of the name. It does not, however, explicitly differentiate itself from the other resolve_* siblings (resolve_actor, resolve_jurisdiction), leaving the agent to infer the distinction from the resource noun.

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 use this tool versus alternatives, no prerequisites (e.g. where a GTIN comes from), and no exclusions. The phrase 'Confirm the product is real' implies a validation use case, but that is inference rather than guidance.

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

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

Annotations already cover safety (readOnlyHint=true, idempotentHint=true, destruction false), so the bar is lower. The description adds a useful domain constraint: there are exactly 20 canonical markets, and UK vs GB mapping is handled. However, it doesn't say whether an unrecognized market returns an error, null, or a fuzzy match.

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 purpose question and followed immediately by the concrete mapping rule. 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?

The tool is simple (one param, output schema present), and the description supplies enough domain context to invoke it correctly, including the canonical market count and alias handling. The only gap is failure behavior for non-canonical inputs, which is minor 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 coverage is 0% and there is a single required 'market' parameter with no enum. The description gives examples (FR, UK, US, Japan) and a critical UK/GB alias rule, which is genuine added meaning beyond the bare string schema. Baseline 3 for a one-parameter tool where the description partially compensates.

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 (resolve) and resource (a market to one of the 20 markets on the record), and gives concrete examples (FR, UK, US, Japan). The phrasing 'Where is the media bought?' frames the domain purpose. It is clearly distinguishable from siblings like resolve_actor and resolve_gtin, which resolve other entity types.

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 — an agent would call this when it has a user-supplied or free-text market that needs normalization to the canonical 20-market vocabulary. The UK/GB acceptance note gives a hint about input tolerance, but there is no explicit guidance on when to use this versus alternatives or what happens on an unresolvable market.

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, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety/mutation profile is covered. The description adds genuine value by disclosing routing logic per banner card status (unclaimed→referral, claimed→retailer media team, registered→agent-to-agent), which is real behavioral context beyond the annotations, though it omits idempotency implications and 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 short but stylized rather than front-loaded: the leading colon-fragment and the cryptic closer 'Settles at the door' spend words without conveying actionable meaning, so it is under-specified rather than genuinely 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 not be described, but for a 9-parameter, 7-required mutation tool the description leaves too much implicit: several parameters, the meaning of the optional note/decision_id, and the practical effect of a successful submission are all unaddressed.

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

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

Schema description coverage is 0% across 9 parameters, so the description must compensate. It names maker, budget, GTINs, market and banners (with the useful constraint that budget is 'a person approved'), but leaves budget_approved_by, contact, note and decision_id entirely unexplained 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 enumerates the packet contents (maker, approved budget, GTINs, market, banners) and states the routing outcome, so the gist of submitting a demand is recoverable. But the operative verb is metaphorical ('Hand off: the packet') and phrases like 'Settles at the door' obscure rather than clarify what the tool actually does, so it stops short of a clean verb+resource statement.

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 'or a gap naming what is missing' hints that a partial packet yields a validation-style gap response, which is useful. However, there is no guidance on when to call this versus siblings like a2a_handoff, receive_demand, quote_package, or gate_transaction, and no stated prerequisites.

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