cash_flow

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that internal transfers are filtered by default, explains what the default totals represent, and clarifies that account= of any type works despite the narrow default. It does not, however, disclose return format beyond the group_by TSV case, or any auth/permission requirements. Still, the core filtering behavior is well documented.

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 well-structured with a clear summary paragraph followed by an Args section. It is moderately long but every sentence earns its place — scope definition, exclusion guidance, filtering behavior, and use cases are all packed efficiently. The prose is tight and front-loaded with the core purpose before diving into edge cases.

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?

There is an output schema present, so the description doesn't need to explain all return values. For a 5-parameter analytical tool with subtle default behaviors (narrow scope, transfer filtering), the description covers the key semantic complexity comprehensively. It could mention output format for the default case (beyond the TSV mention for group_by), but the presence of an output schema mitigates this gap.

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 fully compensate for all 5 parameters. It does: start_date/end_date get format hints (YYYY-MM-DD), account gets default behavior explained, include_transfers gets detailed True/False semantics, and group_by gets the allowed values plus output behavior ('split the range into sub-period columns, Inflows/Outflows/Net trend table'). This is strong compensation for zero schema coverage.

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 opens with a clear verb+resource+scope statement: 'Calculate cash flow (inflows and outflows) for a period.' It explicitly defines the default scope (BANK and CASH accounts) and distinguishes itself from balance_sheet for credit-card/investment movements. The distinction from siblings is notable and specific.

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 explicitly states when NOT to use this tool (credit-card/investment movements should use balance_sheet), explains the default filtering behavior for internal transfers, and gives a concrete use case for include_transfers=true ('reconciling against a bank statement'). It also explains the conceptual distinction between 'where did money come from' vs 'every debit and credit.'

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