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

The readOnlyHint annotation already establishes this as a safe read, so the description isn't carrying the safety burden. It does add domain context beyond the annotation: only completed transactions are returned ('already happened'), and it discloses the endpoint (GET /transaction/{id}). No pagination, rate-limit, auth, or not-found behavior is described, which keeps this at a solid but not rich 3.

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?

A single dense sentence with the operation and key qualifiers front-loaded, followed by the endpoint. Nothing is padded, though the field enumeration is a long inline list that could be trimmed.

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?

There is no output schema, so the description usefully enumerates the returned fields (amount, method, status, applied invoices, related refunds), which is exactly what an agent needs to know before calling. The remaining gap is the absence of any failure-mode or filtering context, but for a single-ID read tool this is close to complete.

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% – the 'id' parameter is documented in the schema as the transaction_id with type and bounds. The description's 'by transaction_id' adds no syntax, format, or sourcing detail beyond that, so the baseline 3 applies.

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 ('Get one transaction') and resource, and disambiguates the domain term by defining a transaction as 'payment, refund or credit that already happened'. It also enumerates the fields returned. It does not name its nearest sibling (chargeover_list_transactions), though the singular 'one' vs. list distinction is reasonably clear from the name.

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?

Usage is implied by 'by transaction_id' – the agent infers this is the lookup path when a specific transaction ID is known. There is no explicit when-to-use guidance, no mention of when to prefer chargeover_list_transactions, and no stated prerequisites or error conditions.

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