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

Annotations declare a non-read-only, open-world, non-idempotent, non-destructive write; the description usefully adds the downstream side effect (a personal editing-test link is emailed to the applicant) and the data-provenance constraint, which annotations cannot express. It stops short of stating duplicate-submission behavior despite idempotentHint=false, or what the caller receives on success.

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 sentences, front-loaded with what the tool does, then the side effect, then the data constraint. No filler and nothing repeated from structured fields.

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 an 8-parameter, non-idempotent submission tool with no output schema, the description covers purpose, side effect, and provenance but leaves out what an agent would want before calling: the role of the optional notes field, duplicate-submission handling, and the shape of a success response.

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 50%: location, software, experience, and portfolioUrl are documented in the schema, while name, email, phone, and the optional notes are not. The description adds a meaningful constraint that all values must come from the applicant rather than being invented, but it does not clarify the four undescribed parameters, so it only partially compensates.

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?

Names a specific verb and resource ('Apply for MadBroad's video editor role') and anchors it to a known external form, so an agent can tell instantly this is the submission tool rather than the lookup siblings (get_role, list_open_roles).

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?

Usage is implied by the role-specific naming and the constraint 'Only use details the applicant has provided,' but there is no explicit when-to-use/when-not, no mention of prerequisites (e.g., confirm with the applicant before submitting), and no exclusions relative to list_open_roles or get_role.

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