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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile needs no restating. The description does add genuinely new context about approval gating (org-configurable MCP approvals, business workflow approvals always apply), but says nothing about pagination limits, result ordering, or empty-result behavior.

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 sentences, only the middle one ("Read invoices for a site") carries the core meaning. The first is boilerplate preamble and the third is generic compliance language that could be appended to any tool in this server.

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's gaps are real but not fatal: the output schema covers return values, and the annotations cover the safety profile, leaving only pagination and sibling disambiguation as notable omissions. That keeps it at the top of the 3-4 range rather than the bottom — scored 5 as adequate-to-good given how much the structured fields absorb. On reflection, the missing sibling disambiguation against three invoice-list tools and the complete silence on pagination semantics are omissions the description alone must fix; scored 3.

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 0%, so the description carries the full burden — yet it only implicitly covers siteId ("for a site"). limit, offset and search are undocumented anywhere: no default paging behavior, no statement that search filters within the site, no max page size guidance.

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?

"Read invoices for a site" is a clear verb + resource + scope, and the required siteId confirms the scoping. It does not, however, distinguish itself from the nearby siblings list_invoices, list_bid_invoices and list_vendor_invoices, so an agent could not pick between them from the description alone.

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 opening clause ("Use this when working with RetailHardHat invoices records in the connected organization") is generic framing rather than a use condition, and no alternative is named. With four invoice-listing siblings in the toolset, the absence of any "use X instead when…" guidance is a real gap.

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