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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description partly reinforces that for reviewConnection ("without changing them"), which is useful. But it then states "connect applies the user's choices", describing a mutating operation on a tool declared read-only, and that action is not even present in the enum — a conflict that could steer an agent into calling this tool expecting a write. Side-effect, confirmation, and scoping behavior for the other actions go unstated.

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 short and front-loads the primary purpose, which is good. But the sentence about "connect applies the user's choices" earns no place — it describes an unavailable action and creates ambiguity — while the enum sentence is the only genuinely load-bearing one after the opener.

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 14-parameter tool with 7% schema coverage, no output schema, and a read-only annotation profile, this description is far too thin: it neither maps the parameter surface nor explains what inspecting balances or connections returns. An agent could fire the call but would be guessing on most inputs.

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?

With 14 parameters and only 7% schema description coverage, the description must carry the parameter burden, and it explains just two: `name` ("Supply name to inspect") and `action` (enum values listed). The other twelve — date, type, names, amount, hidden, offset, confirm, newName, accounts, category, startDate — are undocumented in both schema and description, so an agent has no basis for populating them correctly.

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 opening sentence gives a concrete verb and resource ("List the active company's bank and credit card accounts"), but the rest of the description mashes three sub-operations (list, inspect, reviewConnection) plus a phantom "connect" action into the same tool, so the agent cannot form a crisp picture of what the tool actually is. No sibling is named or distinguished, despite siblings like manage_company and manage_transactions being plausibly adjacent.

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 enumerates the valid action values and hints at what each does ("Supply name to inspect balances and connection details", "reviewConnection reads available account choices ... without changing them"), which is genuine routing guidance. However, it gives no when-not-to-use criteria and never points to an alternative sibling tool, and it advertises a "connect" action that is not in the enum, leaving the agent unsure what to do when it wants to actually connect accounts.

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