Neuron Sports Ad Exchange

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

With no annotations, the description must carry the burden of behavioral disclosure. It adds value by revealing it accesses a 'booking ledger' and distinguishes 'REAL remaining capacity' from published rates. However, it never explicitly states the operation is read-only, nor does it mention authentication, rate limits, or response behavior—gaps that matter for a query tool with zero annotation support.

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

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

Three sentences, no fluff. The first sentence delivers the core purpose and scope, the second gives a clear directive, and the third defines the two price fields precisely. All content earns its place and the description is 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?

There is no output schema, so the description must explain what the tool returns. It covers the main output aspects (formats, list CPM, floor CPM, remaining capacity) but leaves the 'remaining capacity' return unspecified in terms of field names or units. For a tool with only two optional parameters, this is adequate 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 100%, so the baseline is 3. The description does not add meaning to the sport or format parameters beyond what the schema already provides; its added details (list_cpm_usd vs floor_cpm_usd) concern output semantics, not parameter semantics. Therefore the score matches the baseline.

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

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

The description uses a specific verb ('Query') and resource ('live sports advertising inventory'), and names the exact outputs: formats, list CPM, biddable hard floor, and remaining capacity. It differentiates itself from siblings like create_ad_order or submit_programmatic_bid by framing itself as the starting point for discovering availability, making its role 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?

It explicitly says 'Start here to see what is actually available', which establishes a clear primary use case and implies using it before bidding or creating orders. However, it does not name alternative sibling tools (e.g., list_open_tenders, estimate_ad_cost) or provide explicit when-not-to-use conditions, so it falls short of a 5.

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

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

No annotations are present, so the description must bear the full behavioral disclosure. It does disclose the key constraint that the amount is read from the stored quote and cannot be supplied, and that it settles to @neuronsystems. However, it omits details about error handling, idempotency semantics (despite the idempotency_key parameter), and the behavior when both order_id and quote_id are 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?

The description is two sentences with zero wasted words. The purpose is stated first, followed by the key constraint and a usage prerequisite. It is front-loaded and efficient, ideal for agent consumption.

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 has no output schema, so the description should indicate the return value. It says 'Generate a live Stripe Checkout URL', implying the output is the URL, but it does not specify the exact format or any accompanying details. It also does not mention authentication requirements, error scenarios, or how idempotency_key should be used despite being in the schema. For a tool that creates a checkout session, the description covers the core action and prerequisite but omits potential edge cases.

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 already documents all parameters with 100% coverage, providing descriptions for each. The description adds a critical clarification that the amount is not a parameter and is derived from the quote, which helps agents understand the absence of an amount field. It also reinforces the either/or relationship between order_id and quote_id, though the schema already states this. Overall, it adds marginal value beyond the schema.

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

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

The description clearly states the action (generate a live Stripe Checkout URL), the target (existing quote_id or order_id), and the settling entity (@neuronsystems). It also clarifies that the amount is not caller-supplied, distinguishing it from payment tools that accept an amount. This makes the purpose unambiguous and distinct from sibling tools.

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

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

The description explicitly instructs to call estimate_ad_cost first, establishing a dependency and ordering. It implies the tool is for existing quotes/orders, not for creating them, which differentiates it from create_ad_order. However, it does not explicitly state when not to use it, such as for new quotes lacking a cost estimate.

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?

With no annotations present, the description carries the full burden, and it delivers. It discloses that the quote is binding, valid for 30 minutes, returns an exact price, and is a mandatory prerequisite for charging. This goes well beyond the schema and tells the agent what behavioral consequences to expect.

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 tight sentences with no fluff. The core action and key constraint are front-loaded, and every sentence earns its place by providing either the action, the return contract, or the mandatory usage context.

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?

Despite lacking an output schema and annotations, the description provides everything an agent needs to call the tool correctly: what it does, what it returns (quote_id, exact price), how long the quote is valid, and the mandatory ordering relative to other tools. No critical invocation detail is missing.

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

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

Schema description coverage is 100%, so the schema already documents each parameter thoroughly. The tool description does not add meaning to individual parameters beyond what is in the schema. Baseline 3 applies because the schema is doing the heavy lifting.

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

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

The description states a specific action ('Issue a BINDING quote'), identifies the resource ('for a slot'), and names the key return value (quote_id and exact price). It also distinguishes itself from sibling tools by explicitly referencing create_ad_order and create_checkout_session as downstream steps, making its role clear.

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

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

The description gives explicit when-to-use guidance: 'You MUST call this before create_ad_order or create_checkout_session.' It explains why this ordering matters by noting that the quote_id is the only thing that authorizes a charge. This is direct, actionable guidance for selecting and sequencing the call.

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?

No annotations are provided, so the description must cover behavior; 'Retrieve' signals read-only and the metric list indicates what is returned. It does not disclose potential latency, whether settlement status is final or pending, or any side effects, but for a simple read tool this is minimally adequate.

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

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

One sentence with a clear front-loaded verb and object, followed by a compact list of returned fields. There is no fluff or repetition.

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 required parameter, no output schema), and the description lists the key return dimensions. It is slightly incomplete around what 'pacing' and 'settlement status' mean, but an agent can call it correctly with the order_id from the schema.

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% for the single order_id parameter, so the schema carries the semantic weight ('The order ID returned by create_ad_order'). The description adds nothing parameter-specific, matching the baseline.

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

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

The description uses a specific verb ('Retrieve') and a clear resource ('real delivery for an order'), then enumerates the exact data returned. Among siblings like create_ad_order and estimate_ad_cost, it clearly identifies itself as the read-back telemetry 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?

No statement about when to use this tool versus alternatives such as estimate_ad_cost or check_neuron_inventory. The prerequisite that order_id comes from create_ad_order appears only in the schema, not as guidance in the description.

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

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

With no annotations, the description carries the behavioral burden and does so well: it discloses real-time unsold capacity, the ordering heuristic, and the key fields returned, including a cross-reference to estimate_ad_cost. It does not disclose auth requirements, rate limits, or pagination, but those are minor for a read-style listing tool.

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

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

Two tight sentences with no filler: the purpose and ordering are front-loaded, and the second sentence compactly enumerates the return fields and the quoting call. Every clause adds useful 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?

Although there is no output schema, the description explains what each returned tender carries, which is sufficient for an agent to understand the response shape. With three optional self-describing parameters, the tool is simple enough that no critical calling information is obviously missing.

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

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

Schema coverage is 100%, with limit, sport, and format each already described with enums and defaults. The description adds no new meaning about these input parameters beyond what the schema provides, 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?

The description uses a specific verb ('List') and a clear resource ('slots with real unsold capacity right now'), plus a precise ordering rule ('by how close they are to selling out'). It distinguishes itself from siblings like estimate_ad_cost and submit_programmatic_bid by focusing on inventory discovery, not pricing or bidding.

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 the tool is for finding currently available, unsold inventory and even points to estimate_ad_cost for quoting. However, it does not explicitly state when to prefer this over sibling tools like check_neuron_inventory or submit_programmatic_bid, nor does it mention any exclusions or limitations.

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?

With no annotations, the description carries the disclosure burden and does a good job: it explains the broker's decision paths (auto-accept returning a spendable quote_id, counter, or reject) and the hard floor rule. It does not explicitly flag broader side effects or authorization needs, but the primary behavior is transparent.

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

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

Three sentences front-load the core action, then compactly convey evaluation outcomes and the acceptance threshold rule. There is no filler, and each 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?

Despite having no output schema and no annotations, the description covers the key outcomes (quote_id, counter, reject), the floor threshold, and how to source required values from sibling tools. It omits explicit retry/idempotency behavior and other error cases, but the essential call contract 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?

All 7 parameters already have schema descriptions, so coverage is 100% and the description need not redefine them. It adds useful color around bid_cpm_usd by tying it to acceptance thresholds, but the schema already does the heavy lifting.

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

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

The description clearly states the action ('Bid a CPM against a slot') and the resource, and distinguishes this from the sibling check_neuron_inventory by treating it as the source of the acceptance threshold. It does not explicitly contrast with order, checkout, or estimating siblings, so it stops short of a perfect 5.

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

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

The description gives concrete guidance: bid at or above min_acceptable_cpm_usd from check_neuron_inventory or a prior response, use list_open_tenders to obtain tender_id, and never expect acceptance below floor_cpm_usd. It provides clear context but does not explicitly state when-not-to-use this tool versus alternatives.

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