trial_balance_by_period

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

With no annotations, the description carries the full behavioral burden. It does disclose two genuinely useful traits beyond the schema: computation happens server-side in SAP rather than via table reads, and full-year results are written to an Excel file as a side effect. It says nothing about read-only safety, permissions, runtime, or whether the Excel write can be suppressed, which leaves real gaps for a report of this weight.

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?

Four tight clauses, each carrying distinct information: what is computed, how periods define opening, the optional filters, and the Excel side effect. The output structure is front-loaded and nothing is repeated from the schema or title.

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?

An output schema exists, so return values need not be described, and the description instead covers computation source, period semantics, and the Excel artifact. What remains unaddressed is authentication and whether this is a safe read, which matters given the absence of annotations on a 7-parameter report tool.

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 must compensate and largely does: it explains that periods run 1-16, that opening balance equals all periods before period_from (a semantic the schema cannot express), that the account range is optional, and that ledger defaults to 0L. Only company_code and fiscal_year are left to inference, and both are self-evident from their names.

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 report (trial balance), its source table (ACDOCA), the engine (SAP), and the exact columns produced: opening incl. carry-forward, period debit/credit, closing, with names. That is far more specific than the name alone and clearly separates it from siblings like open_items_ageing or read_sap_table. It stops short of explicitly naming which sibling to use instead, so a 4 rather than a 5.

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 only implied: the reader can infer this is the tool for period-based trial balances and that account range is optional, but there is no statement of when to prefer it over grir_differences, open_items_ageing, or run_sap_report, nor any prerequisite such as required SAP login. Guidance is present but must be reconstructed from the parameter hints.

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