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

Annotations only declare readOnlyHint and openWorldHint=false; the description adds substantial context beyond that: the three possible outcomes (available/partial/unavailable), the partial-volume and viewable-share fields, the fallback alternatives, and critically that figures are forecast estimates rounded down, not reservations. That last point prevents an agent from treating the result as a booking.

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

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

Three tight sentences, front-loaded with the core action and then the return semantics. Every clause earns its place; nothing is redundant with the name or annotations.

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

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

With no output schema, the description carries the full burden of describing the return value, and it does so thoroughly: outcome states, partial volume, viewable share, alternative periods/families, and the estimate-not-reservation caveat.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters (token, period, family_id, impressions, client_request_id). The description only hints at a rounding default ('2 significant figures by default'), which does not add parameter-level syntax beyond the schema. Baseline 3.

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

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

States a specific verb and resource with scope: checks whether the publisher can deliver N impressions of a product family in a period. This is clearly distinguishable from siblings like get_forecast (retrieves forecasts) and create_intent (commits a buy).

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 (a pre-commit availability probe before create_intent) but never stated explicitly, and no sibling alternative or when-not condition is named. The agent must infer the place in the workflow from the sibling list.

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

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

Annotations declare readOnly=false, destructive=false, idempotent=false, and openWorld=false, so the safety profile is covered. Beyond that, the description adds genuinely useful semantics: the commitment is 'soft' and has a TTL, which an agent cannot infer from the annotations. It omits what happens at TTL expiry and does not surface the mandatory client_request_id replay requirement, keeping it below 5.

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

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

Two tight sentences: the core action and its soft-commitment/TTL nature come first, with the disambiguation clause front-loaded immediately after. Every clause earns its place and nothing is redundant.

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

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

With a rich 100%-covered input schema, an explicit annotation set, and no output schema, the description supplies the essential conceptual framing (soft commitment, TTL, not an order/hold). It is nearly complete, missing only lifecycle details such as expiry behavior or the interaction with the revoke_intent sibling.

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

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

Schema description coverage is 100%, so every parameter (token, period, family_id, price_ref, client_request_id) is already documented in the schema. The description's 'at its current firm price' loosely reinforces price_ref but adds no format, constraint, or edge-case detail beyond what the schema states.

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 ('Register a firm buying intent over a product family') with the key qualifier 'at its current firm price' and the semantic nature ('soft commitment with TTL'). The final clause 'Not a GAM order or inventory hold' actively distinguishes it from realistic confusions like check_availability and other order-like 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?

The 'Not a GAM order or inventory hold' exclusion tells the agent when this tool is the wrong choice, which is meaningful routing guidance. It does not, however, explicitly point to a positive alternative (e.g. check_availability for stock, revoke_intent for withdrawal) or state preconditions like needing a family_id from discover_products, so it stops short of a full 5.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the useful qualifier 'coarse', implying the result is an aggregated/high-level view rather than a full catalog, but it says nothing about pagination, filtering, or that identity comes from the token.

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 'coarse' carries a lot of unexplained weight for one adjective.

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 discovery tool with annotations covering safety and a 100%-covered schema, the remaining gap is the return shape: there is no output schema, yet the description does not characterize what a 'coarse product family' looks like or how results are ordered/limited. Adequate but leaves an agent guessing about output.

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

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

Schema description coverage is 100%, and both parameters (token, client_request_id) are documented in the schema itself with detail on RS256/JWT and idempotency. The description adds nothing beyond that, so the baseline 3 is appropriate.

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

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

States a specific verb ('discover') and resource ('product families') with a scope qualifier ('available to this buyer'). It is distinguishable from siblings like get_forecast or check_availability, though it does not name what makes it different beyond the 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?

There is no when-to-use guidance, no prerequisites, and no pointer to alternatives such as well_known_capabilities, which a sibling for discovery/capability listing. The agent must infer the entry point from the 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 cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds real behavioral context beyond them: the result is bucketed rather than numeric, and the `synthetic` flag discloses whether the bucket derives from a live ad-server forecast or a fallback. That provenance disclosure is genuinely useful for trusting the value, though nothing is said about staleness or caching.

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

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

Two tight sentences, zero filler, and the scope statement precedes the return-value note. Every clause earns its place.

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

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

With no output schema, the description does carry part of the return-value burden and does so adequately (bucket scale plus the synthetic provenance flag). The main residual gap is routing guidance against check_availability, which is outside the strict return-value remit.

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

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

Schema coverage is 100%, so family_id, period, token, and client_request_id are all documented in the schema. The description only restates the family/period inputs and does not add format, range, or default semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Get), resource (availability forecast), granularity (coarse Low/Mid/High), and the two dimensions it is keyed on (product family, period). It is clear what the tool does, though it never explicitly contrasts itself with the sibling check_availability, which sounds like the adjacent retrieval tool.

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 word 'coarse' and the Low/Mid/High scale imply this is the cheap planning-grade lookup rather than a precise availability check, which is a usable hint. But there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. versus check_availability), so the agent must infer the 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 destructiveHint=true and idempotentHint=true, so safety and repeat-call behavior are covered structurally. The description adds useful detail beyond that: idempotency is keyed on client_request_id, and the constraint that only the caller's own active intents can be revoked.

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, no padding, and the core action plus scope is front-loaded before the idempotency note.

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

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

For a destructive but idempotent mutation with full schema coverage and complete annotations, the description covers enough: what it does, on what scope, and idempotency semantics. Only a fuller statement of failure behavior (e.g. what happens to an already-revoked or expired intent) is missing, and no output schema exists to defer to.

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

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

Schema description coverage is 100%, and all three parameters (token, intent_id, client_request_id) are documented in the schema itself, so the baseline of 3 applies. The description adds no format or syntax detail beyond what the schema already says.

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 (revoke) and resource (intent) with scope qualifiers ('one of your own active') and the lookup key ('by id'). It is easy to distinguish from create_intent, though it never names a sibling 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?

Usage is implied by the words 'your own active intents', which tells the agent the target must be an existing intent it owns, but there is no explicit when-to-use/when-not guidance or named alternative among the 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 and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context by specifying the document is signed with RS256 (a verifiable trust anchor), but it says nothing about whether the endpoint is public or needs auth, or how the signature should be validated.

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 identifies the resource and its key property (signed RS256). No filler, no redundancy with 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?

No output schema exists, so the description carries the return-value burden; it names the artifact but not what the capability document contains or how to consume the signature. For a simple discovery endpoint this is borderline adequate, but an agent gains little actionable detail about the payload.

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

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

The tool takes zero parameters and the schema is an empty object, so there is no parameter semantics to explain. Per the baseline for 0-param tools, a 4 is appropriate; the description correctly implies no inputs are needed.

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 ('Return') and a well-defined resource ('signed RS256 capability document for this Seller MCP Node'), which is clearly distinct from transactional siblings like create_intent or check_availability. It does not explicitly name or contrast with siblings, but the resource is unique enough that confusion is unlikely.

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 indication of when an agent should call this versus discover_products or the other siblings, nor any prerequisites or call ordering. The well-known/trust-anchor nature implies a discovery/bootstrap use, but that must be inferred entirely by the reader.

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