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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety and mutability. The description adds value by specifying that the data is dynamic ('30-day change', 'roles posted in the last 30 days') and that 'history exists' conditionally, which is useful context 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?

The description is two sentences with no fluff. The first sentence front-loads key information about outputs and usage, and the second clarifies the purpose ('find who is hiring most or pulling back'). Every word earns its place.

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 a single optional parameter, no output schema, and annotations covering safety, the description is largely complete. It covers what data is returned, the ranking basis, and the use case. One minor gap: it doesn't mention the default limit or whether pagination exists, but these are minor for this simple tool.

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%, but the only parameter is 'limit', which is self-explanatory from the schema's name, default, and constraints. The description doesn't elaborate on it, but there's not much to add. The parameter's meaning (controlling number of results) is implicit, so a baseline of 3 is fair.

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 resource ('Companies under hiring coverage'), a clear action ('ranked by open roles'), and lists exact outputs ('30-day change', 'roles posted in the last 30 days', 'top function', 'top country'). It clearly differentiates from siblings like company.hiring (which likely focuses on a single company) by emphasizing a market-wide ranking perspective.

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 description provides clear context: it's for finding who is hiring most or pulling back. It implies a market-level view, which distinguishes it from company.hiring. However, it doesn't explicitly state when not to use it or name alternatives, but for a simple, single-purpose tool this is acceptable.

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