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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is fully covered by structured data. The description does add useful scope detail (what is counted) and a data-quality caveat — salary ranges only 'where posts state them' — which is genuine behavioral context. It does not mention default month behavior or result limits, so it is solid but not rich.

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 front-loaded sentence that enumerates exactly the returned metrics with no filler. The 'where posts state them' qualifier earns its place by setting expectations about missing salary data.

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?

An output schema exists, so return-value structure need not be explained here, and all parameters are optional with sane defaults, making invocation trivial. The one gap is that the undocumented 'top' parameter is left for the agent to guess at, but otherwise the definition is complete for its intended aggregate use.

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 67%; 'month' and 'response_format' are documented in the schema, but 'top' (integer, default 20, range 5-60) has no description anywhere, and the description never says what it truncates. The description adds no parameter meaning beyond the schema, so the baseline 3 for moderate coverage 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 concretely what the tool returns: job post counts, work-mode and visa shares, top skills, and salary ranges for a single month. That is a specific aggregation resource an agent can recognize. It does not, however, differentiate itself from siblings like skill_demand or hiring_threads, which likely overlap on the skills dimension.

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?

There is no explicit when-to-use guidance, no mention of when not to use it, and no reference to any of the four sibling tools. The phrase 'one month at a glance' weakly implies an aggregate-overview use case, but the agent must infer that itself.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is well covered without the description. The description adds that results include comment counts and links, a modest behavioral/return detail beyond the 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?

A single front-loaded sentence with no filler; the resource and its distinguishing contents are stated immediately.

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?

An output schema exists, so return structure need not be spelled out, and the annotations cover the safety profile for a simple read-only list tool. The only gap is the absence of any sibling-routing guidance, which the description could have supplied.

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 100%, so both parameters (months, response_format) are already fully documented with defaults, bounds, and enum values. The description adds no syntax or format detail beyond the schema, making the baseline 3 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 gives a specific verb ('List') and resource (monthly 'Who is hiring?' threads) and notes the payload (comment counts and links). It does not explicitly name or contrast with the sibling tools (search_jobs, hiring_snapshot, skill_demand), so it stops short of a 5.

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?

There is no statement of when to use this tool versus search_jobs or hiring_snapshot, and no prerequisites or exclusions. The agent must infer usage from the tool name and the four sibling names alone.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds genuinely useful behavioral context beyond them: the analysis compares the recent half of the period against the earlier half and draws on ~70 known skills. It does not disclose output shape or damping/limitations, but the method disclosure is the substantive part.

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 tight sentence, front-loaded with the analytic question and then the comparison method. No filler, though the '~70 known skills' detail is somewhat optional.

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?

An output schema exists, so return-value explanation is not required, and the comparison methodology is stated. However, with two of three parameters undocumented anywhere, an agent still cannot confidently size 'top' or interpret 'months' from the definition alone.

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 only 33% -- 'top' and 'months' carry no descriptions in the schema. The description's reference to 'the period' loosely ties to 'months' but never explains what 'top' caps or how the two halves are derived. With low coverage, the description should compensate and does not.

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 gives a specific analytical verb and resource: it identifies which skills gained or lost demand by comparing mention shares between two halves of a period. That is concrete and distinguishable from a level-check like skill_demand, though it never names a sibling or explicitly contrasts itself with them.

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 framing ('gained or lost demand') -- an agent can infer this is the trend/change tool rather than a static demand tool. But there is no explicit statement of when to prefer this over skill_demand or the hiring_* siblings, and no exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful detail by listing the returned fields (company, header line, salary if stated, link), but that overlaps with the existing output schema, and nothing is said about result ordering or truncation.

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?

Two tight sentences: the search scope is front-loaded, then the return shape. Every clause earns its place with no restating of the name or title.

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 annotations covering safety and an output schema covering return structure, the description only needs to frame the search; it does that well. Minor gaps remain around pagination/limit behavior and the 'monthly threads' window, which is a domain concept a new agent may not know.

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% (terms, months, response_format documented; limit, visa_only and remote_only not). The description compensates slightly by naming the remote-only and visa-sponsoring behaviors behind two of the undocumented flags, which is more than the schema alone provides, but it says nothing about limit or the months window.

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 ('Find') and resource ('job posts') plus the matching semantics ('mention all the given terms'), so the agent knows exactly what this returns. It does not, however, differentiate itself from siblings like hiring_threads or skill_demand, which also surface job-market data.

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 mention of 'optionally remote-only or visa-sponsoring' implies the filtering context in which each flag matters, but there is no explicit when-to-use guidance, no exclusions, and no pointer to a sibling for aggregate/analytics queries.

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

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

Annotations already declare readOnly, idempotent, open-world and non-destructive behavior, so the safety profile is covered. The description adds genuine behavioral value by stating the output includes a delta between the oldest and newest month, which is not derivable from the schema. It stops short of noting aggregation or sampling caveats.

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 tight sentence with no filler, and the core measure is front-loaded. The trailing clause about the oldest-to-newest change is slightly awkwardly worded but still earns its place as behavioral content.

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?

An output schema exists, so return shape need not be explained, and all three parameters are documented in the schema. What the tool computes and that it includes a trend delta is clear; only sibling routing guidance is absent.

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 100%, with months, skills and response_format all documented in the schema itself (including the tuned-matching note for known skills). The description adds no parameter-level syntax or constraints, 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?

The description names a specific computation — monthly share of job posts mentioning a skill, plus the change from oldest to newest month — so an agent knows exactly what is produced. It does not, however, differentiate itself from the sibling 'rising_skills', which sounds like an adjacent trend-over-time tool.

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 measurement it performs implies a use case (tracking demand for named skills over time), but there is no explicit statement of when to pick this over 'rising_skills' or 'hiring_threads', nor any exclusion. Usage is left to inference.

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