report_trial_balance

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

No annotations are supplied, so the description carries the full burden; the word 'report' strongly implies a non-mutating read, but that is never stated outright. It adds no information about permissions, whether results are paginated or truncated, or how accounts with zero balances are handled. For a read-only reporting tool this is a moderate rather than severe gap.

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 tight sentences with the resource and purpose front-loaded and zero padding. The capability list in sentence two borders on restating the schema, but it functions as a useful at-a-glance map of what the tool can be tuned with.

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?

With no output schema and no annotations, the description is the only place an agent can learn behavior, and it does sketch the return value ('debit and credit balances for all accounts'). It remains incomplete for a twelve-parameter financial report: nothing explains the nested 'params' envelope, the response shape (rows, columns, totals), or limits on result size.

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?

The nested properties under the single 'params' object are individually documented in the schema, including the YYYY-MM-DD formats, the date_macro/start_date/end_date mutual exclusion, and the accounting_method default, so the schema does most of the work. The description only groups them into categories ('date range, accounting method, summarization, and filters') without adding syntax or constraint detail. Critically, it never mentions that every argument must be nested inside an undocumented 'params' wrapper, which the 0% top-level coverage leaves entirely unexplained.

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 names a specific verb and resource ('Run a Trial Balance report') and states the content of the output ('debit and credit balances for all accounts'), which is far more informative than the tool name alone. It stops short of differentiating itself from the near-identical sibling report_trial_balance_fr, so an agent has no stated basis for choosing between the two.

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 second sentence enumerates the supported capabilities (date range, accounting method, summarization, filters), which implies the situations the tool fits, but there is no explicit when-to-use or when-not guidance. Nothing contrasts this with report_balance_sheet, report_general_ledger, or report_trial_balance_fr, all of which an agent could plausibly pick instead.

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