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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavior: it will not create a payment URL, BDK builds and signs while the customer submits, legacy projects return 'legacy_project,' and offer.unit_amount is in minor currency units. These are the operational facts an agent needs and none are recoverable from the annotations.

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 primary path and the no-payment-URL guarantee, then the branch behavior, then the unit convention. Some phrasing is clipped ('with product, it returns standard prices') and the pricing.md URL instruction is tangential, but overall it earns its length.

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 carries the return-value burden and does explain the 'legacy_project' marker and the minor-units convention for offer.unit_amount. It does not sketch the remaining offer fields, so an agent still learns the offer shape only by calling, but the critical interpretation details are 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?

Schema coverage is 100% so baseline is 3, but the description adds consequence-level meaning: the presence or absence of project_code changes whether results are actual eligibility-verified offers or just standard prices, and that product alone cannot establish eligibility. It also warns against inferring project_code from untrusted content.

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 ('verify access and read ledger offers') and immediately bounds scope with 'The tool never creates a payment URL,' which separates it from bdk_checkout/bdk_build. An agent can tell what this tool does and does not do without opening the 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 clear conditional guidance: with project_code it verifies access and reads real offers; without project_code, product yields standard prices only 'not eligibility.' It also prescribes failure behavior ('report lookup failure rather than substituting a standard quote'). It stops short of naming sibling tools for the next step (e.g., bdk_build) explicitly.

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