BestBid Agent Sponsorship

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context beyond annotations by stating data comes from the live database and that only active rankings are addressed, which implies freshness and a constraint on accepted slugs.

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 two short sentences with no filler. The first sentence front-loads the action and object, and the second adds a relevant data-freshness detail. Every word earns its place.

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

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

For a simple read tool, the description covers the core return content (paid positions and prices), the single-ranking scope, and the live data source. It does not explain the limit parameter's effect or behavior for missing/inactive rankings, and there is no output schema, but the annotations sufficiently cover the safety aspects.

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 for parameter meaning. 'One active ranking' hints that slug identifies a single ranking, but the description never mentions the limit parameter or explains what it controls, leaving a required semantic gap for 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 uses a specific verb ('Read') and resource ('paid positions and prices for one active ranking'), making the tool's function immediately clear. The singular 'one active ranking' distinguishes it from broader search/listing tools like search_rankings, and 'paid positions and prices' separates it from sponsorship-focused 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 description implies when to use the tool: when you need current paid position and price data for a specific active ranking. However, it does not explicitly state when not to use it or point to an alternative like search_rankings for finding or listing rankings, leaving the routing partially 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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by specifying exactly which information is read (rules, terms version, payment availability, agent wallets), which goes beyond the annotations and helps set response expectations.

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, concise sentence that front-loads the verb and resource, then adds the 'before buying' usage context. Every word earns its place with no redundancy.

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

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

For a zero-parameter, read-only tool with no output schema, the description covers the key return categories and usage timing. It is slightly less detailed on exact output structure, but the listed items are sufficient for an agent to select and call it 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?

The tool has no parameters and the schema is empty, so there are no parameter semantics to document. The description is not required to add parameter detail; the baseline of 4 for zero-parameter tools applies.

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

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

The description uses a specific verb ('Read') and clearly names the resource: BestBid advertising rules, terms version, live payment availability, and supported agent wallets. It is clear, but it does not explicitly differentiate itself from siblings such as get_sponsorship_status or get_ranking, relying mainly on the enumerated content.

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 'before buying' provides clear contextual timing for when this tool should be used, distinguishing it from purchase or quote actions. However, it does not name alternatives or state when not to use this tool versus get_sponsorship_status.

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 operation as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond these: it emphasizes privacy, explicitly states what the result will not contain (payer identity and payment provider identifiers), and instructs polling behavior. This adds value without contradicting the annotations.

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

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

Two sentences with no filler. The primary purpose is front-loaded, followed by a pragmatic polling directive and a concise privacy guarantee. Every phrase 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?

The description conveys purpose, polling behavior, and privacy constraints, which covers a lot for a read-only status tool. However, with no output schema, it does not specify the response format or what 'confirmed' concretely returns (e.g., payment and publication booleans, confirmation flags). An agent would need to infer the confirmation condition and response structure from limited information.

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, but it never mentions orderId or statusToken or explains their roles. The privacy-focused wording hints that statusToken enables access without identifying the payer, but this is not explicit. Parameter names are somewhat self-descriptive, yet the description adds no direct semantic value to the schema fields.

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 ('check payment and publication') and a resource ('sponsorship status'), making the core purpose clear. The privacy qualifier and the note about lacking payer identity help differentiate it from a public info tool, though it does not explicitly name a sibling alternative.

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 instruction 'Poll until confirmed' gives clear operational guidance on how to use the tool repeatedly. However, it does not explain when to choose this tool over siblings like get_sponsorship_info or quote_sponsorship, leaving the selection context largely implicit.

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

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

Annotations already mark this as non-read-only and idempotent, but the description adds meaningful behavioral detail: save the returned orderId and statusToken, retry the same quote after a timeout, and never create another payment while an order is processing. It also clarifies that payment metadata comes from the wallet integration, so no separate payment parameter is needed.

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 front-load the action, then cover prerequisites, then provide operational guidance on response handling and retry behavior. Every sentence earns its place, and there is no filler or repetition of the schema.

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

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

The description covers the action, prerequisites, protocol choices, returned values (orderId/statusToken), and retry policy, which is substantial given there is no output schema. It leaves the prerequisite quote flow implicit rather than referencing quote_sponsorship, but the core information needed to call and use the tool is 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 description coverage is 0%, so the description must carry parameter meaning. It maps protocol to MPP/x402, acceptedTermsVersion to 'exact current terms acceptance', and authorizedToPromote to 'authority to promote the URL'. However, quoteId and quoteToken are only implied through 'quoted' and 'same quote', not explicitly explained, so compensation is partial.

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

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

The description opens with a specific action verb and clear object ('Buy the quoted sponsored placement') and identifies the payment protocols ('via MPP or x402'). This clearly distinguishes the tool from siblings like quote_sponsorship (which creates a quote) and get_sponsorship_status (which checks status).

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

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

The description makes it clear that this is the purchasing step for an existing quote and that it requires current terms acceptance and authority to promote the URL. It does not explicitly name sibling tools or state when not to use it, but the context is clear enough for an agent to route correctly.

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 are all false, providing little behavioral signal. The description adds meaningful context by stating no charge/reservation occurs and by instructing to keep quoteToken private. This goes beyond the annotations and clarifies side-effect expectations, though it does not address other potential side effects like creating a quote record 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?

Three short sentences, all essential. The main action is front-loaded, the non-charge/reserve qualifier prevents confusion with purchase_sponsorship, and the privacy note is a necessary operational warning. No redundant or filler content.

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 and zero parameter documentation, the description leaves critical gaps: no explanation of the quoteToken output or its lifecycle, no guidance on strategy or targetTotalCents, and no mention of how the quote relates to a subsequent purchase. The description is too sparse for a 5-parameter tool with this complexity.

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 but only addresses maxPaymentCents ('within maxPaymentCents'). It does not explain rankingSlug, productUrl, strategy, or targetTotalCents, nor does it clarify the meaning of the strategy enum values. Minimal semantic value is added over the raw schema.

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

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

The description states a specific verb ('Get'), a concrete resource ('sponsorship quote'), and distinguishes itself from purchase_sponsorship by explicitly noting it does not charge or reserve a position. The five-minute validity and maxPaymentCents constraint add further precision, making the tool's purpose unmistakable.

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 clear context: it is for obtaining an exact quote before any commitment, and it clarifies what it does not do (charge or reserve). However, it does not explicitly name sibling tools like purchase_sponsorship as the alternative for the actual purchase, leaving some inference to the agent.

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 indicate readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description adds meaningful context beyond annotations: 'Reading is free' signals no cost for reads, and 'Rank is paid placement, not endorsement' clarifies the interpretation of results. No contradiction with annotations 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?

The description is three short sentences with no filler. The primary purpose is front-loaded, and the second and third sentences add valuable interpretive context about cost and the meaning of rankings. Every sentence earns its place.

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

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

For a search tool with no output schema and no parameter descriptions, the description provides the core purpose and interpretation but leaves gaps. It does not explain what a result entry looks like, how limit interacts with the query, or whether category refines or changes the search. It is reasonably complete but not fully self-sufficient.

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 for parameter guidance, but it does not explicitly describe limit, query, or category. It only hints at query semantics through 'for your agent, product, brand or service.' Limit and category remain unexplained, leaving the agent to rely on parameter names alone.

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 uses a specific verb and resource: 'Find active paid advertising rankings for your agent, product, brand or service.' It clearly distinguishes this from the singular get_ranking sibling by focusing on searching multiple active paid rankings. The added context about paid placement further disambiguates the meaning of 'rankings.'

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 conveys that this tool is for finding active paid advertising rankings, which implies its primary use case. However, it does not explicitly contrast it with get_ranking or the sponsorship-related sibling tools, nor does it state when not to use it. Usage context is present but 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 the operation as readOnly=false, idempotent=true, and destructive=true. The description adds meaningful behavioral context by explaining the access/ownership rule behind edit authorization, which is not captured by annotations. No contradiction exists between the description and annotations.

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

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

The description is two sentences with no filler. The main action is front-loaded, and the second sentence earns its place by clarifying an authorization nuance that could otherwise cause failed calls.

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 update tool with no output schema and no parameter-level descriptions, the description covers the key access condition but leaves statusToken semantics and the exact effect of the update under-specified. It is adequate for a simple tool but not 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 compensate, but it only names 'tagline' and 'description' as the content being updated. It provides no explanation for 'orderId' or 'statusToken', and no guidance on formats or required semantics beyond what parameter names suggest. This leaves a notable gap for a required-parameter-heavy mutation.

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

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

The description clearly identifies the update action and the resources being modified ('tagline and description'), making the tool's purpose evident. It adds a scope condition ('only when the private order capability controls the listing') that helps distinguish it from purchase or quote operations, though it does not explicitly name sibling alternatives.

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 an explicit precondition for use: only when the private order capability controls the listing. It also provides a clear when-not condition: paying to boost someone else's listing does not grant edit access. This is strong usage guidance that prevents erroneous calls.

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