bulkUpdatePeople

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

With no annotations, the description carries the full burden. It discloses the rate-limiting behavior and that results are returned per person. Could add detail on partial failures or default tag behavior, but the key operational traits are covered.

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, front-loaded with the main purpose, then two crucial behavioral notes. Every word earns its place; no redundancy or filler.

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 batch operation with nested objects, the description covers purpose, rate-limit safety, and result format. The rich schema fills param details. Missing edge-case behavior (e.g., invalid IDs, partial success) but acceptable for typical agent use.

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 provides 100% coverage with descriptive parameter descriptions. The description adds no extra semantic value beyond the schema; it reinforces that updates use the same fields as updatePerson, which the schema already states.

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 the action ('Update'), resource ('multiple people'), and the key qualifier ('with the same changes'). This distinguishes it from single-person update tools like updatePerson.

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?

Implies the use case: applying identical changes to multiple people. The rate-limit note suggests using this for bulk operations to avoid hitting FUB's API limits. Does not explicitly name updatePerson as an alternative, but context makes it evident.

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