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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the write-vs-read ambiguity is worse than it looks: the tool is annotated as a non-mutating, idempotent operation even though its name implies authoring. The description adds useful context that the output includes a compliance check (pay range rules by location, citizenship wording, exclusionary language, requirement inflation), which is behavior beyond the annotations. It does not say whether anything is persisted, so the name/annotation tension is never resolved.

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?

One dense sentence that front-loads the verb and resource and then packs four compliance dimensions into a colon list. It is efficient but the list feels like feature enumeration rather than guidance, and the core drafting behavior (output format, sections) is never stated.

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?

Enough to know what the tool roughly does and that it returns a compliance check, but with no output schema the description should say more about what comes back (a draft? a report? both?) and how it relates to lint_job_post. For a content-generation tool in a crowded sibling set, that is a real gap.

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 already documents both params, including that details accepts a scorecard/notes with ownership, stack, team, pay range, remote rules, locations and benefits. The description lists the compliance dimensions but adds no parameter syntax or format information beyond the schema. Baseline 3 is appropriate.

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 states a specific verb (Write) and resource (software engineer job post), and adds secondary scope (compliance check) that distinguishes it from the closest sibling lint_job_post. It doesn't explicitly name alternatives, but the purpose is clear and specific.

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?

No when-to-use guidance and no exclusions. The overlap with lint_job_post is left unresolved; an agent cannot tell from the description whether drafting (this tool) vs. reviewing an existing post (lint_job_post) is the intended split, or whether both should be run.

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