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

With no annotations, the description carries the behavioral burden and discloses key traits: the tool is restricted to the operator, idempotent, and returns success with credits_granted=0 for already-credited invoices. It also clarifies that a BTCPay-settled invoice is the precondition, although it does not describe failure handling for non-settled invoices.

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 front-loaded with the core action and restriction, and every paragraph contributes: purpose, access rule, use cases, and idempotency. The use-case list is a bit domain-specific but earns its place by defining exactly when to invoke the tool.

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 restricted financial mutation tool, the description covers who may call it, the trigger conditions, the idempotency semantics, and the key success behavior. The output schema exists, so return-value documentation is not required in the description, and nothing essential for correct invocation is missing.

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 the schema already documents all three parameters fully. The description adds some domain context, such as the patron's ledger and credited_invoices idempotency, but it does not need to compensate for missing 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?

The description opens with a specific verb and resource: "Credit a patron's ledger from a BTCPay-settled invoice." It goes beyond the title by defining the restricted manual credit-grant action and distinguishing it from ordinary purchase/check flows via the RESTRICTED-to-operator note and enumerated incident use cases.

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 gives explicit when-to-use context through use cases like "cold-start vault races during check_payment" and "infrastructure incident that left an invoice settled at BTCPay but uncredited." It also states who may invoke it and the escalation path for patrons, but it does not explicitly name an alternative sibling tool to use instead.

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