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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and scope are covered structurally. The description adds a bit by indicating each result carries stage and note, but says nothing about ordering, pagination, result volume, or whether hidden jobs are included by default. With annotations doing the heavy lifting, this is adequate but thin.

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?

A single short sentence with no filler and no repetition of the title. It is front-loaded with the scope qualifier 'the user's'. It could be denser with information, but nothing in it is wasted.

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 tool whose only complexity is two same-vocabulary enum params, the description leaves the central ambiguity (stage vs state) unexplained and gives no default behavior when both are omitted. No output schema exists, so the terse 'with stage and note' is the only hint about return shape, and it is insufficient for an agent to predict results.

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 0%, so the description must carry the burden, and it does not. Two params with overlapping vocabularies ('stage' with saved/applied/interview/... and 'state' with all/saved/applied/hidden) are genuinely confusable, and the description never explains the difference, nor the defaults for the two optional params.

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 names the resource (the user's own saved/applied/hidden jobs) rather than a verb, but 'the user's' does implicitly distinguish it from siblings like search_jobs, new_jobs, and company_jobs. 'With stage and note' gestures at payload contents but is compressed to the point of ambiguity. An agent gets the gist but no crisp action statement.

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 framing and no named alternative. With 17 siblings including new_jobs, similar_jobs, and search_jobs, the absence of any routing guidance leaves the agent to infer that this is the personal/private list versus the discovery lists. Nothing states when not to use it or what preconditions apply.

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