Book a Sponsor

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

Beyond the annotations (idempotent, non-destructive, open-world), the description discloses two behaviors the agent could not infer: it starts a scan of public newsletter pages if none exists, and that scan takes roughly 15-60 seconds. The latency and the implicit scan-start explain why readOnlyHint is false and let the agent set expectations for the caller.

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 ordered as use-case, mechanism/output, and operational caveat, so the critical information is front-loaded. The trigger sentence is slightly repetitive ('which brands might sponsor it or how to find sponsors for it'), a minor wordiness cost.

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 tool with an output schema, the description covers the trigger, the processing mechanism, the shape of results, and the scan latency. Nothing an agent needs to call it correctly or explain the wait to a user 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?

There is a single parameter with 100% schema description coverage, including a format example, so the schema already carries the semantics. The description only restates that it takes 'the newsletter's web address' and adds no syntax or constraint detail beyond the schema, which is the baseline 3 case.

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 concrete verb chain (takes a URL, finds similar newsletters, returns their sponsors with run dates) and names the target user, so the purpose is unmistakable. It does not explicitly contrast itself with siblings like get_sponsor_scan or get_newsletter_sponsorship_rates, which keeps it short of a 5.

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

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

It states the triggering situation clearly: 'Use this when someone who runs a newsletter asks which brands might sponsor it or how to find sponsors for it.' That is solid when-to-use guidance, but it offers no when-not-to-use conditions or pointer to an alternative sibling 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 readOnly=true, idempotent=true, destructive=false, so the safety profile is covered. The description adds genuine value beyond them: it discloses the underlying data source (advertise pages) and the precise metric (median price for the main sponsor slot of a single issue).

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 first front-loads the usage trigger, the second defines the return. No filler, nothing 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 an output schema present and full annotation coverage, the description does not need to explain return values, and it correctly focuses on trigger and metric. Nothing an agent needs to invoke this correctly 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% and the single parameter is documented in the schema. The description adds only the notion that subscribers map to a 'size band,' which is marginal clarification over the schema; baseline 3 fits.

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 clear verb and resource: it returns the median listed sponsorship price. It also scopes the result ('main sponsor slot of one issue, by list size') and names the data source ('their own advertise pages'). It does not explicitly distinguish itself from the siblings, but the purpose is distinct 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?

It gives explicit trigger phrasing ('Use this when someone asks how much to charge for a newsletter sponsorship or what newsletters charge for an ad'), which is strong context. It stops short of naming when-not-to-use or pointing to a sibling as an alternative, so it is not 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 already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine value by disclosing the asynchronous scan lifecycle (this reads the result of a previously started scan). However it omits behavior on a not-yet-finished or expired scan, and any polling/rate guidance.

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, zero waste, with the routing condition front-loaded before the parameter 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?

An output schema exists, so return values need not be explained, and the description covers the trigger and the parameter's identity requirement. The remaining gap is error/edge-case behavior (scan not found, not finished, expired), which an agent would need for robust polling.

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% and the schema description already says the URL is 'used for find_newsletter_sponsors'. The description's 'takes the same newsletter web address' reinforces identity matching between the two calls, but adds no syntax or format detail beyond the schema, so 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+resource ('read the result of a sponsor scan') and explicitly anchors it to the sibling that creates that state, find_newsletter_sponsors. An agent can distinguish this polling tool from the initiating tool and the other sibling rate/brand tools without opening any schema.

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 a concrete trigger condition: use it when find_newsletter_sponsors reported the scan was still running. The alternative (the initiating tool) is named, though there is no explicit guidance on when NOT to call it (e.g. completed/expired scans) or how often to poll.

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, so safety is covered; the description adds genuinely new behavioral context in the form of the 12-month lookback window and the data source ('read from published issues'). It doesn't mention result size, pagination, or freshness beyond the window, which keeps it from a 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 sentences with no filler: the first front-loads the trigger condition and optional topical scope, the second states what comes back. 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 an output schema present, return shape need not be explained, and annotations cover the safety profile. The description supplies the ranking basis and time window, which are the key interpretive facts; missing only minor framing such as result cap or how 'seen in the most newsletters' is ordered.

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 the single enum parameter is fully documented in the schema, so the baseline is 3. The description's mention of topics like AI, finance or marketing loosely illustrates the niche filter but adds no syntax or semantics beyond the enumerated values.

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+resource (list brands sponsoring newsletters) plus the scope of the result: brands ranked by how many newsletters they appeared in over the last 12 months. It is clear on its own, but it never differentiates itself from close siblings like find_newsletter_sponsors or get_sponsor_scan, leaving that to inference.

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 opens with an explicit usage trigger ('Use this when someone asks which companies or brands sponsor newsletters, overall or in a topic'), which tells the agent the question shape this tool answers. It stops short of naming alternatives or stating when another sibling is the better pick, so no exclusions are given.

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