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

Annotations already flag this as destructive and non-idempotent. The description adds meaningful context by disclosing the cost per credit, pack size, and the necessity of a stored payment method, which collectively imply a monetary charge. It does not describe failure modes or post-purchase effects, but the annotation coverage already handles the core safety profile, so the additional context is valuable.

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 tightly organized: it opens with the purpose, follows with cost and usage context, states a prerequisite, and ends with a compact Args section. Every sentence serves a clear function and there is no extraneous information, making it easy to quickly parse.

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 two parameters, an output schema, and annotations present, the description covers purpose, pricing, prerequisite, parameter semantics, and usage context. It leaves little ambiguity. A small gap is the lack of explicit statement about what happens after a successful purchase (e.g., credits added to account), but given the output schema, the agent can infer the response, so this is a minor gap.

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, and it does so fully. 'packs' is explained as the number of 100-credit packs with a default of 1, and 'api_key' is described as the Disco API key with an environment variable fallback. This adds detailed meaning that the schema lacks.

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 the exact action with a specific verb and resource: 'Purchase Disco credit packs using a stored payment method.' It clearly distinguishes itself from siblings like discovery_add_payment_method by focusing on the purchase itself, and even names the use case (private analyses). This is unambiguous and specific.

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 tells the agent to use discovery_add_payment_method first as a prerequisite, which is a clear 'when-to-use' signal. It also provides context that credits are for private analyses, implying this tool is needed when private analyses are required. However, it does not explicitly list when not to use it or alternative tools (e.g., discovery_subscribe), so it falls just 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.