find_contacts

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 adds meaningful context: the balance is the total outstanding (not invoice-level), the name_contains is case-insensitive, include_inactive defaults to active only, and limit is capped at 500. It also clarifies that omitting name_contains lists everyone. While it doesn't explicitly state that the operation is read-only, 'Look up' implies this, and the added semantics go beyond what the schema provides. A small gap is the lack of details on potential errors or authentication requirements, but for a simple lookup tool this is reasonably transparent.

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 and concise. It starts with a clear one-sentence summary, then a brief usage sentence, a sentence providing contextual detail about the balance, and finally a neatly formatted Args list. Every sentence adds value, and the parameter documentation is easy to scan. No unnecessary fluff.

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 that the tool has four optional parameters and no annotations, the description covers all essential aspects: purpose, usage, parameter semantics, and a key behavioral nuance (balance is total outstanding). It also directs users to an alternative for more detailed aging information. Since an output schema exists, the description doesn't need to explain return values. This is a complete and self-sufficient description for effective tool selection and invocation.

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?

The input schema has zero description coverage, so the description must compensate, and it does so thoroughly. The Args section explains each parameter: name_contains as a case-insensitive partial name with the behavior when omitted, kind as 'customer' or 'vendor', include_inactive as toggling archived records with a default of active only, and limit with a maximum cap. This adds substantial meaning beyond the raw schema defaults and 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 clearly states the tool's function: 'Look up customers or vendors, with contact details and balances.' It specifies the resource (contacts) and the action (look up), and further elaborates with concrete use cases like finding by partial name, listing all business contacts, or retrieving email/phone. It distinguishes from the sibling tool get_receivables_aging by explicitly mentioning it as an alternative for invoice-level detail, which helps with sibling differentiation.

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 to use this tool ('Use to find someone by partial name, to list who the business deals with, or to get an email or phone number') and provides an alternative: 'for invoice-level detail and overdue days use get_receivables_aging.' This is clear, actionable guidance on both when to use this tool and when to choose a different one.

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