quickbooks_list_payment_methods

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

Annotations already supply the read-only, non-destructive, idempotent safety profile. The description adds some genuinely new context: the strict routing through the governed connector authority and that effect is required to be 'read' and verified by Spring. It does not contradict the annotations. Flagging it a 3 because operational behavior (pagination, result size, failure modes) is left to the output schema and inference.

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 compact and easy to scan, with the parameter list front-loaded by the routing note. But the opening line is a pure restatement of the tool name and burns a sentence; the remaining content earns its place, so it lands at a mid threshold rather than above.

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 output schema covers result shape, and annotations cover mutation risk and idempotency, so those gaps are filled. The description covers auth/routing and parameters, but never actually defines the domain purpose or the fact that it's a list (no pagination hint, no object- meaning for payment method, no guidance that it's a read/observation-only operation). Considering the 7-param complexity, this is usable but with distinguish gaps.

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 parameter burden and it largely compensates by giving each parameter a meaning beyond type/default: arguments' JSON string, project_id as UUID, connector_account_ref as account alias, idempotency_key as the business identity, effect's must-be-read applies, and the purpose of approval_ref. The points are only terse and the approval_ref note feels misplaced on a read tool, hence a 4 not 5.

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's first sentence ('Quickbooks connector operation list_payment_methods (platform tool quickbooks.list_payment_methods)') merely restates the tool name — a tautology. It never states that this lists payment methods in QuickBooks, what a payment method is in that context, or what the call returns, and with dozens of quickbooks_list_* siblings present, that clarity gap is meaningful.

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?

There is no when-to-use or when-not-to-use guidance and no alternatives named. The routing sentence ('Routes only through the exact project/account governed connector authority') is an invocation route, not a usage rule. An agent selecting between a dozen 'quickbooks_list_' siblings has to depend on the name alone.

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