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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the bar is lower. The description adds valuable domain-specific context: it is an accounting record and does not initiate a bank or card payment. This goes beyond the generic read-only annotation by clarifying the real-world side effect that is NOT triggered, which helps prevent misuse.

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?

Two sentences with no filler. The primary purpose is front-loaded, and the clarifying exclusions follow immediately. Every sentence earns its place—nothing extraneous.

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 simple get-by-Id tool with fully documented schema parameters and no output schema, the description provides all essential context: what it retrieves, how it identifies it, and what it does not do. Combined with annotations indicating safety, an agent has enough to select and invoke this tool correctly.

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%, with both 'id' and 'company' already described. The description only restates that retrieval is 'by Id', adding no new meaning to the parameters. Per the baseline rule, when the schema fully documents parameters, score 3, and the description does not elevate it.

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 first sentence uses a specific verb and resource: 'Get a single bill payment from QuickBooks Online by Id.' It clearly identifies the object (a bill payment, as opposed to a general payment) and method (by Id). The second sentence adds identity as 'an accounting record of a payment to a vendor,' distinguishing it from customer payments and from tools like create_bill_payment or search_bill_payments.

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 states 'It does not initiate a bank or card payment,' which is an explicit exclusion that routes agents away from using this tool for payment initiation. It also implies retrieval use via 'Get ... by Id' without naming alternatives like search_bill_payments. This is clear context but lacks an explicit 'use X instead when' statement, so it stops 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.