macaroons_purchase

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

With no annotations, the description carries full burden and does an excellent job: it discloses hold-invoice settlement, refund-on-failed-predicate, no-wallet default behavior, and the need to pay a returned invoice manually. Nothing important is hidden.

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, with the core purpose first, the payment settlement mechanism second, and the no-wallet fallback last. Every clause earns its place and the unusual L402 behavior is explained compactly.

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?

The description covers the complex payment semantics, refund path, and fallback despite no output schema or annotations. It is slightly incomplete about what a successful paid response contains, but the phrase 'change-events' and rich input schema make the remaining gap minor.

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%, so the baseline is 3. The tool-level description mostly restates what the predicate and resume_macaroon schemas already say, adding no substantive parameter-level insight beyond the structured descriptions.

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 opens with a specific verb and object ('Purchase change-events for a feed target') and names the resource being acted on. The paid/retrieval nature and the feed-target scope distinguish it from search, metadata, and execute siblings.

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 explains the payment flow and fallback behavior, and references feed target id from macaroons_metadata, giving some contextual guidance. However, it never explicitly states when to prefer this tool over macaroons_search or macaroons_execute, nor does it give when-not-to-use conditions.

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