balance_delete

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

No annotations provided, so the description carries the full burden. It does disclose the soft-delete nature and that it cascades to parsed account rows, which is valuable behavioral context. However, it doesn't explain what 'soft-delete' means practically (e.g., whether the balance disappears from list views, whether rows are recoverable, audit implications). For a delete operation with no annotation coverage, this is adequate but not rich.

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 short sentences that deliver clear value: the verb+resource statement plus the soft-delete cascade disclosure. Efficient and front-loaded. No filler or redundancy.

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?

This is a straightforward delete-with-id tool. The description plus 100% schema coverage covers the essentials. However, for a mutating operation with no annotations and no output schema, it could state what a successful delete returns (e.g., confirmation, deleted object, or empty). The soft-delete semantics are disclosed but the practical implications are left ambiguous. Adequate but with room to improve.

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 100%, with both 'id' (Trial balance UUID to delete) and 'companyId' (Company UUID overrides STORNO_COMPANY_ID env var) documented. The description adds the context that deletion cascades to parsed account rows, which is useful. Since schema already covers the parameters well, baseline 3 is appropriate.

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 clearly states 'Delete an uploaded trial balance by ID' with a specific verb+resource+scoping mechanism. It also discloses the soft-delete behavior ('soft-deletes the balance and its parsed account rows'), which distinguishes it from a hard delete. It doesn't explicitly contrast with siblings like balance_reprocess or balance_rows, but the delete action is unambiguous.

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?

No guidance about when to use this versus alternatives, or when one should prefer balance_delete over other trial balance operations. It doesn't mention any exclusions, prerequisites (e.g., whether balance must exist), or scenarios where deletion would be inappropriate (e.g., balances referenced by reports). No mention of irreversibility beyond soft-delete.

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