billy_period_overview

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

Annotations already cover read-only, idempotent, and non-destructive behavior, so the description does not need to restate that. It adds the important behavioral caveat that candidate matches are suggestions, not an accounting verdict, which is meaningful context beyond the annotations. This helps the agent interpret results correctly without overstepping.

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 sentences with no fluff or restatement. The first sentence front-loads the action and scope, and the second quickly delivers the key interpretive caveat. Every word earns its place.

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 read-only, idempotent tool with a simple three-parameter schema, the description communicates what is inventoried and how to interpret the output. The absence of an output schema makes the item enumeration and 'not an accounting verdict' caveat valuable. It does not specify exact output structure or period inclusivity, but the annotations and simple schema reduce the need for more.

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 for parameter meaning. It partially does by clarifying that start and end define a period and that the output includes specific record types, but it does not explain the optional verbose flag or date-boundary behavior. The schema provides patterns and defaults, and the parameter names are fairly intuitive, making this adequate though not thorough.

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 concrete action ('Inventory') and specifies the resource scope: unreconciled bank lines, postings, bills, and collected receipts over a period. This clearly distinguishes it from more generic sibling tools like billy_list or billy_get, though it does not explicitly call them out. The caveat about candidate matches further sharpens its purpose.

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 phrase 'for a period' implies this tool is intended for period-scoped overviews of reconciliation-related entities, and the listed item types suggest when it would apply. However, there is no explicit guidance on when not to use it or which sibling tool to prefer for different needs, such as billy_outstanding or billy_get. This is adequate but relies on the agent to infer usage.

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