tally_search

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses date-range limitations for vouchers, ignores date range for masters, per-type caps with a 'truncated' flag, voucher matching coverage, a prompt-injection warning about text fields, and a read-only guarantee. This far exceeds the minimum for behavioral transparency.

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 long but every section earns its place: purpose, when-to-use, returns, scope/limits, and safety warning. It is prominently front-loaded with the core function and structured with clear headings, making it scannable. Nothing is wasted.

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?

Given six parameters, no output schema, and multiple sibling tools, this description is remarkably complete. It explains the return shape (matches grouped by entity type with summaries), the fallback follow-up tools, and the precise behavioral limits that affect interpretation of empty results. The user knows exactly what to expect and what to do next.

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?

Although schema coverage is 100%, the description adds significant meaning beyond the schema. It explains that fromDate/toDate only affect vouchers, that limit caps are per type and 'truncated' signals an incomplete result, and that entityTypes is the main way to make the call faster because each type costs a separate Tally request. This is genuine added context, not mere repetition.

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, specific verb: 'Search across ledgers, vouchers and stock items at once for a name, number or reference.' It explicitly distinguishes itself from sibling tools like tally_search_ledgers, tally_search_vouchers, and tally_search_stock_items by stating that once the entity type is known, the specific tool is better.

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 'WHEN TO USE' section explicitly states the use case: when you do not yet know what kind of thing you are looking for. It also tells when NOT to use it and points to alternatives, noting that specific tools 'return full records and support proper filters.' This is exactly the kind of when/when-not guidance expected.

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