ashby_bulk_archive

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

The destructiveHint annotation already signals the operation is destructive, and the description adds batch limits, reusable archiving logic, a caching optimization, and the response shape. It does not go deeper into side effects such as partial failures or how sending emails behaves beyond the schema, so the extra behavioral context is moderate rather than 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?

The description is short and front-loaded: first the action, then limits and relationship to the sibling tool, then the return format. No sentence is filler; the response format is valuable because there is no output schema.

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 destructive batch operation with no output schema, the description provides the essential invocation context: batch limit, relation to the singular tool, and the exact response shape. It could add an explicit note about the interplay between send_email and email_template_id, but that dependency is already documented in the input schema.

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 the parameters are already fully documented. The description adds only general framing ('optional reason and rejection email') and the 25-ID limit, which is also in the schema; that meets the baseline but does not go beyond it.

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 specific verb and resource: 'Archive multiple applications at once,' and clearly frames this as the bulk version of ashby_archive_application. It names the sibling tool and says it uses the same archiving logic, so an agent can tell them apart immediately.

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 makes the batch use case clear and explicitly ties the behavior to ashby_archive_application, which implies the singular tool is the alternative for one-off archiving. It does not explicitly state when-not conditions or directly compare the two tools, but the routing is easy to infer.

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