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

Annotations only declare readOnlyHint and openWorldHint, so the description carries the extra load and does: it discloses hard operational limits ('Up to 5 upwork_id per call, 30 jobs per hour') and a scoping constraint that prevents bulk lookups. These are exactly the behavioral traits an agent cannot infer from annotations.

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 tight sentences: what it returns, when to use it and when not to, then the rate limits. The scoping rule is front-loaded before the limit, and no sentence is expendable.

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?

With no output schema, the description must enumerate the return shape, and it does (experience level, duration, workload, category, client spend/rating/hire rate/history). Combined with the rate limit and shortlist constraint, an agent has everything needed to call this correctly and sparingly.

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 single parameter already documents its maxItems of 5 and its origin in find_jobs. The description restates the same 5-per-call limit and the id source without adding format, validation, or error semantics beyond the schema, so the baseline 3 applies.

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 specific verb and resource ('Full data of jobs returned by find_jobs') and enumerates exactly what is returned: experience level, duration, workload, category, client statistics. It explicitly anchors the tool to its sibling find_jobs as the source of the ids, so an agent can tell these two apart without opening schemas.

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 both when-to-use ('Only for jobs already shortlisted by title, description and skills, when the user needs more to decide') and an explicit exclusion ('never for every job found'). The alternative path (find_jobs) is named as the origin of the input, leaving no routing ambiguity.

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