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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety and repeat-call profile is covered without the description. The description adds only that the return contains 'full text and parsed fields', which is modest extra context beyond the structured fields; no error or rate-limit behavior is disclosed.

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 sentence, front-loaded with the verb and result shape, with the id-provenance hint in a compact parenthetical. No wasted words.

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 an output schema present, the description need not explain return values, and annotations carry the safety profile, so the short description is close to sufficient. The only real gap is behavioral/edge-case guidance (missing or nonexistent id), which is not required but would complete the picture.

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 'id' parameter is already documented as the HN comment id of the job post, so the baseline is 3. The description adds provenance ('from search_jobs'), telling the agent where a valid id comes from, which is genuinely useful beyond the schema.

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 (Returns) plus resource and scope: 'full text and parsed fields of one job post by its HN id'. It distinguishes itself from the list/search siblings implicitly by being a single-item fetch, though it never names a sibling as an alternative the way an ideal routing hint would.

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 parenthetical '(from search_jobs)' implies the workflow: obtain the id from search_jobs first, then call this tool. That is useful implied usage, but there is no explicit when-to-use vs. when-not, and no mention of what happens if the id is invalid or the post is gone.

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, and openWorldHint=true. The description adds valuable latency context ('The first call for many months can take ~1 s per uncached month'), which is behavioral information not captured by annotations. It does not mention output structure, but with an output schema present, that is less critical.

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 sentences, front-loaded with the core computation, followed by an example and a performance caveat. No wasted words.

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?

The tool has an output schema, so the description needn't explain return values. It covers the computation, an example use case, and latency. It could be slightly more complete by clarifying the 'months' parameter or noting any data freshness limits, but it is largely sufficient for correct invocation.

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%: the 'technologies' parameter is well documented with an example, but 'months' has no description. The description states 'the last N monthly threads', implying the 'months' parameter controls the window but doesn't clarify the default (6) or maximum (12) beyond what the schema already provides. Baseline 3 is appropriate given partial schema coverage.

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 precise computation: 'For each of the last N monthly threads, counts how many posts mention each technology and how many offer remote/hybrid/onsite.' This is a specific verb (counts) applied to specific resources (posts, technologies, work modes), and it is clearly distinguishable from siblings like list_hiring_threads (enumeration) and search_jobs (search).

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?

It gives a concrete example use case ('is demand for Rust growing?'), which tells the agent when this tool is appropriate. However, it does not explicitly state when not to use it or name the sibling alternatives, so it stops short of full routing guidance.

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 and openWorldHint, so the safety profile is covered. The description adds the useful 'newest first' ordering and monthly cadence context, but says nothing about how many threads are returned or what the default limit behavior is. Modest added value over 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 tight sentence with the key ordering constraint front-loaded after the resource. No wasted words, though it is arguably a touch thin given the unaddressed limit parameter.

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 values need no explanation, and the tool is simple with one optional param. Still, the description omits the limit semantics and any routing guidance among the three siblings, leaving gaps an agent would benefit from having closed.

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?

The single 'limit' parameter has 0% schema description coverage and is never mentioned in the description, so its purpose, default (6), and maximum (24) are invisible to the agent. With coverage this low the description needed to compensate and does not, though the omission is small given only one param.

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 ('Lists the most recent monthly "Ask HN: Who is hiring?" threads') plus ordering ('newest first'), so the agent knows exactly what comes back. It is distinguishable from siblings like search_jobs and get_job by the fact that it returns threads rather than individual postings, though it never names those siblings explicitly.

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 when-to-use or when-not-to-use guidance and no mention of the alternative tools (search_jobs, get_job, hiring_trends). The agent must infer that this is a discovery/browsing entry point versus a search endpoint. Only implied usage is conveyed.

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/openWorld/idempotent, so the safety profile is covered; the description adds real value by disclosing the return shape ('compact summaries') and the filter-combination semantics ('AND'). It omits pagination behavior of limit/offset and doesn't explain the relationship between month and list_hiring_threads.

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 searches, how filters behave, and where to go for more. The scope constraint and routing hint are front-loaded with zero filler.

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 10-param search tool with an output schema, the description covers purpose, filter logic, and the get_job handoff, so return values need no explanation. It is slightly incomplete on pagination and on how the month parameter relates to list_hiring_threads, but nothing critical for a correct call is missing.

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?

With 70% schema coverage, the schema already documents most parameters (defaults, patterns, enum hints). The description contributes the key cross-parameter semantics the schema cannot express: filters are optional and combined with AND. It adds nothing for individual params like sort or offset, but the combination rule is meaningful.

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 ('Searches ... "Who is hiring?" posts') and pins the scope to 'one month,' which no sibling covers. It also distinguishes itself from get_job by noting it returns compact summaries rather than full text, so an agent can route correctly 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 clear usage context: all filters are optional and AND-combined, and it explicitly routes to get_job for full post text. It stops short of stating when *not* to use it (e.g. vs. hiring_trends for aggregate trends, or list_hiring_threads to discover valid months).

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