Apply to Job

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

The description goes beyond the annotations by detailing that it rewrites the resume and cover letter, submits on the employer's system, spends applications and AI credits, and that a submitted application cannot be withdrawn. It also flags idempotency behavior (alreadyExisted) and error handling guidance, all of which are not in the annotations. This fully discloses the destructive, non-idempotent nature in concrete terms.

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 long but each sentence earns its place; it is front-loaded with the core purpose and then methodically covers identifiers, behavior, side effects, error handling, and alternatives. While it could be tightened, the density is justified for a destructive, high-stakes operation.

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 the complexity of the operation (external submission, side effects, error handling), the description covers all necessary aspects: how to identify the job, what the tool does, side effects, retry guidance, and follow-up tools. The existence of an output schema means return values don't need to be spelled out, and the description is complete for an agent to invoke 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 description coverage is 100%, so the baseline is 3. The description adds value by explaining that job_match_id must come from aiapplyd_get_matches and that job_url works for any posting, plus clarifying that mode applies only to this application and never changes user settings. These semantics go beyond the schema's field-level descriptions without being redundant.

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 'Apply to one job on the user's behalf,' which states a specific verb and resource. It further distinguishes itself by explaining how to identify the job (via job_match_id from aiapplyd_get_matches or job_url) and explicitly says not to use it for saving or skipping matches, directing to aiapplyd_triage_matches. This makes it clear among the 16 siblings.

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?

It provides explicit when-to-use guidance: 'apply only to jobs the user chose' and gives exact alternatives for other actions: 'Do not use it to save or skip a match; use aiapplyd_triage_matches.' It also maps next steps (aiapplyd_get_applications, aiapplyd_review_application) and clarifies the mode semantics, leaving no ambiguity about when to invoke this tool versus other tools.

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