Santa's Calling

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

Annotations declare a non-read-only, open-world, non-idempotent operation, and the description adds substantial context beyond them: no charge occurs at call time, the checkout link expires in 30 minutes, and the post-payment email/redemption flow is spelled out. The seasonal cutoff (24 December) is exactly the kind of constraint annotations cannot express.

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?

Front-loaded with the outcome and price before the flow narrative, and the Args block is scannable. The middle passage describing the parent's redemption steps is longer than strictly needed for an agent deciding whether to call the tool, though it does inform expectations about what happens after.

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 correctly names the return value (checkout_url) and what it is, plus the expiry window. Combined with full parameter coverage and the end-to-end flow, an agent has everything needed to invoke this correctly and explain the result to a user.

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 and mostly does: it explains that buyer_name is shown to the family, buyer_email drives receipt and gift link, recipient_email sends the link onward, and message is capped at 300 characters. Minor gap — promo_code gets only a restatement ("a promotion code, if the buyer has one") with no format or validity guidance.

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?

Opens with a specific verb and resource: "Start buying a gift: a phone call from Santa for a child in the UK, £6.99." It immediately distinguishes itself from siblings like check_gift_status by making clear this initiates a purchase rather than checking one, and names the artifact returned (checkout_url).

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 context is clear — this is the entry point of the purchase flow, usable until 24 December, and nothing is charged until the buyer pays on the Stripe page. It does not explicitly name alternatives or say "use check_gift_status after payment," so the agent must infer the sequencing from the sibling names.

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 real value beyond that by disclosing the conditional return behavior: the gift link appears only once paid, and it is also emailed to the family. It does not say what is returned when unpaid or what happens with an invalid gift_id.

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, no filler, and the payoff (the booking link) is surfaced immediately after the core status answer. Every clause carries information the agent would otherwise have to guess.

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 single-parameter read tool with no output schema, the description covers the essential return semantics and the workflow position. Minor gaps remain around the unpaid case and failure handling, but nothing blocks a correct call.

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 gift_id is undocumented in the schema itself. The description partially compensates by implying the id originates from buy_gift_call, but it gives no format, source field name, or error behavior for an unknown 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?

"Whether a gift started with buy_gift_call has been paid" states the specific resource (gift) and the exact fact returned (payment state), and it names the sibling that creates the gift so the agent can place it in the workflow. It falls short of a 5 only because the verb is expressed as a question rather than an explicit action.

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?

Mentioning that the gift is "started with buy_gift_call" implies the tool is used after a purchase to poll for payment, which is useful context. There is no explicit statement of when not to use it, no mention of polling cadence, and no reference to the other siblings (get_faq, get_info).

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, and an output schema exists to describe return values. Beyond that, the description adds only a topic list — nothing about whether the content is static or generated, whether it is scoped to a session/order, or how it behaves if no questions 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?

A single short sentence with zero filler, front-loading the audience and the covered topics. It is a fragment rather than a full statement of action, which is the only structural weakness.

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 parameterless, read-only, non-open-world tool with a declared output schema, the description is essentially sufficient: an agent knows what content comes back and that invocation carries no arguments or risk. The only missing piece is routing guidance versus the get_info 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?

The tool takes zero parameters, so there is no parameter semantics for the description to clarify; the schema itself is complete. Baseline 4 applies for a parameterless tool.

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 concrete content the tool surfaces — call flow, cost, safety, phone compatibility, missed calls, refunds — so an agent can tell this is the informational FAQ resource rather than a transactional sibling like buy_gift_call or check_gift_status. It is a noun-phrase topic list with no verb, and it never distinguishes itself from the vaguer get_info sibling, so it stops 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?

There is no explicit when-to-use statement and no mention of alternatives such as get_info or check_gift_status. Usage is only implied by the phrase 'Parents' frequently asked questions', leaving the agent to infer that informational/pre-purchase questions belong here.

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 that the payload bundles pricing, gift mechanics, safety and links, which helps the agent anticipate content, but nothing about freshness, personalisation inputs, or volume of returned material.

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, front-loaded with the core identity of the service and then the concrete data it returns. The parenthetical price/duration/age block is dense but earns its place by pre-empting the most common follow-up questions; only the trailing 'Includes ...' clause is mildly 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?

For a zero-parameter, read-only info tool with no output schema, the description covers what the response will contain and the commercial context (UK-only, £6.99, ~3 minutes, ages 2-16). That is sufficient for correct invocation; only the get_faq boundary is left unresolved.

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 empty, so there is nothing for the description to disambiguate. Baseline 4 applies since parameter semantics are a non-issue here.

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 resource and enumerates its contents (price, how a gift works, safety, links), so an agent knows this is a product-information retrieval tool. It does not, however, differentiate itself from the sibling get_faq, leaving overlap between the two informational 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?

Usage is only implied: an agent can infer this is the entry point for 'what is this service / what does it cost' questions, and the presence of buy_gift_call and check_gift_status makes the transactional alternatives reasonably clear. No explicit when-not or get_faq-vs-get_info routing is given, which is the main weakness.

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