ashby_archive_application

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

Beyond the destructiveHint annotation, the description reveals useful behavior: it automatically resolves the 'Archived' interview stage and can send a rejection email. It also lists the response fields, which is helpful because there is no output schema. It does not expand on reversibility or side effects, but the annotation already signals destructiveness.

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?

Three short, purposeful sections: a one-sentence action statement, a workflow, and a response shape. No filler or redundant restatement of the 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 single-application mutation with 100% schema coverage and destructiveHint, the description is nearly complete: it gives the workflow, automatic stage resolution, and response fields. It could add guidance on sourcing application_id or when to use bulk_archive, but those are not required to call this tool correctly.

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 coverage is 100%, so the schema carries the detailed parameter meanings. The description adds value by linking archive_reason_id and email_template_id to the specific list tools that produce them and clarifying the optional 'reason' and 'rejection email' concept.

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 a specific action and resource: 'Archive an application' with optional reason and rejection email. It is clear but does not explicitly distinguish itself from sibling ashby_bulk_archive or ashby_move_application_stage, so it misses the top score for explicit 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 gives a concrete workflow with prerequisite calls to ashby_list_archive_reasons and ashby_list_email_templates before invoking this tool. It does not explicitly state exclusions or when to prefer ashby_bulk_archive, but the sequencing and prerequisite guidance are clear.

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