Run a reply check: plan, read, mark, finish

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

Goes well past the annotations by disclosing per-action behavior: start is read-only and repeatable, read authenticates with a locally stored app password the agent never sees and changes nothing, mark mutates stars/labels per the user's Settings choice, and finish advances the last-check watermark, which changes future read results. It also lists failure modes (unknown action, missing saved login, server login refusal). With destructiveHint=false but real state mutation, this is exactly the context an agent needs.

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?

Front-loaded with a one-line purpose, then cleanly sectioned into Use/Behavior/Returns/Errors, so an agent can scan to the part it needs. It is dense and parenthetical-heavy, and the Returns block is long, though that length is largely licensed by the absence of an 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 four-mode state machine with no output schema, the definition covers sequencing, authentication requirements, mutation semantics, and the full return shape of each action (plan, email list with field names and ordering, mail_action, last_check). Errors are enumerated, so nothing material is missing before a call.

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 already 100%, so baseline is 3; the description adds value by tying parameters to the state machine (mark depends on an email id returned by read, and the mark supplants the freeapply_record_outcome kind), which the schema alone does not connect. It stops short of restating per-parameter requirements, so it is incremental rather than exhaustive.

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?

States a concrete verb and resource ("Runs one email reply check") and explicitly names the coupled sibling freeapply_record_outcome for recording each found email, so the boundary is clear without opening any schema. It also names the two mailbox paths (freeapply reader vs Gmail connector), which distinguishes it from the account/settings tools in the sibling list.

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 "Use:" line gives an explicit ordered protocol — start first, then read via freeapply reader or the Gmail connector, mark after each read email is recorded, finish once everything found is recorded. Exclusions are stated too (finish "only after recording everything found"), leaving nothing to inference.

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