search_gifts

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

No annotations provided, so description carries full burden. It discloses date-range support and the filtering limitation but omits behavioral details like pagination behavior, whether results are sorted, or any permissions required. 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 concise sentences. First states purpose, second provides use case and a key limitation. No filler or redundancy; excellent front-loading.

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?

Adequate for a search tool with 5 parameters but no output schema. Covers primary filtering and a limitation, but does not describe the return format or what 'search' means beyond dates (e.g., does it search by gift amount, type, etc.?). Missing output details moderate completeness.

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%, so baseline is 3. The description adds no extra meaning beyond what the schema provides; it only reinforces 'by date range' which is already clear from from_date/to_date fields.

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?

Clearly states 'Search gifts across all constituents by date range' with a specific verb, resource, and scope. Distinguished from siblings like search_constituents and get_constituent_gifts by emphasizing broad cross-constituent search with date filtering.

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?

Explicitly mentions use case ('totals and reconciliation questions') and gives an example. Also notes a limitation (no fund/amount filtering) and a workaround. However, does not explicitly tell the agent when not to use this tool versus alternatives like get_constituent_gifts for individual lookup.

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