Follow Up on Applications

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

The annotations only flag destructive/openWorld/non-idempotent generically; the description concretizes them: send "cannot be undone", draft "spends tokens", send requires a connected Gmail or Outlook under the user's own name, and the exact approved text must be shown before sending. It also prescribes recovery behavior on timeout or error (call action history before retrying), which is behavior an agent cannot infer from annotations or schema.

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 critical constraint (explicit user approval before send) is front-loaded after the action breakdown, and the safety-relevant sentences (irreversibility, mailbox dependency, retry rule) are all load-bearing. It is dense but not padded; the only mild redundancy is restating per-action parameter needs that the schema enum also lists.

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?

An output schema exists, so return shape needn't be described. For an 8-parameter, multi-mode, destructive tool, the description covers consent, auth dependency, cost, failure recovery, ordering, and sibling routing — nothing an agent needs in order to call any action correctly is missing.

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% and the action enum already documents per-action parameter needs, so the baseline is 3. The description still adds value by mapping actions to their side effects and ordering (list = most urgent first) and by tying parameters to workflow steps, though it largely mirrors the enum text rather than adding new syntax.

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?

Opens with a specific verb+resource+scope ("Follow up on applications that have gone quiet") and then decomposes the five action modes so the agent knows exactly what the tool does in each mode. It explicitly separates itself from the closest confusable sibling (aiapplyd_reply_to_email) rather than leaving that to inference.

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?

Gives explicit when-to-use guidance ("Next: action draft for an application from the list"), a when-not-to-use exclusion ("Do not use it to answer an email an employer sent; use aiapplyd_reply_to_email"), a required consent protocol for send, and a fallback path when no mailbox is connected. That is routing, prerequisites, and alternatives in one place.

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