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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds value beyond that: it confirms free accounts are permitted, surfaces the specific response fields to inspect (plan.is_paid, balance), and warns about a false-positive activation signal — meaningful behavioral context for a gating read.

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, front-loaded with the core action, then conditional guidance, then a warning. Every sentence earns its place: what it reads, who can call it, when to call it, and the trap to avoid.

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?

No output schema exists, and the description names the two fields that actually drive the decision (plan.is_paid, balance), which is sufficient for an agent to act. It does not enumerate other plan attributes a caller might see, a minor residual gap for a zero-parameter read.

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 nothing for the description to disambiguate; baseline 4 applies. The mention of plan.is_paid and balance is output-side context rather than parameter documentation.

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 and resource: read the active plan and remaining data credits. The possessive 'your active plan' implicitly differentiates it from dealmachine_plans (catalog of plans) and dealmachine_usage, though neither sibling is named explicitly.

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: after a Stripe payment, call this before retrying an approved enrichment, and check plan.is_paid plus balance. It also gives an explicit negative rule ('a checkout URL or the user saying they paid is not proof of activation'), though it never names dealmachine_checkout or dealmachine_plans as the alternatives.

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