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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds real value beyond that: data source and freshness ("the builds digest, hourly"), the meaning of each status (dependency -> blockedBy which dependency failed), sort order, and return content ("with the last success of each"). Only auth/rate-limit context is absent.

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?

Dense but front-loaded: the verb/resource/scoping sentence comes first, followed by two short fragments on ordering and return content. It is telegraphic rather than wasteful, though the run-on enumeration of statuses is a little heavy.

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 9 params and no output schema, the description should carry return-value burden, and it does partially explain result content (why from the log, an excerpt, last success). It leaves other params (system, package, blocked_by, since, reason, limit) to the schema, which fully documents them.

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%, so the baseline is 3. The description nevertheless adds semantics the schema lacks, explaining what the status categories mean (e.g. dependency failures expose blockedBy) and what each sort yields ("newest" vs "longest failing first"), which genuinely helps parameter selection.

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 ("Search Hydra's builds of nixpkgs master that aren't ok") and enumerates the four status categories it returns. An agent can immediately tell this is a read-only failure-listing tool, distinct from siblings like find_packages or needs_attention.

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 scope description (finding non-ok builds), but there is no explicit when-to-use, when-not, or named alternative. Siblings such as needs_attention and update_attempts could overlap, and nothing here routes the agent between them.

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 and openWorldHint=true, so the safety profile is covered. The description adds useful context beyond that: the values come from meta.json files, and it also reports what the server has cached. It does not mention cost, latency, or whether cached data can be stale relative to the files.

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 parenthetical '(their meta.json files)' is slightly awkward but it is the one piece of implementation detail that clarifies where the timestamps originate, so it 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?

For a zero-parameter, read-only status tool with no output schema, the description covers the three things returned: per-digest timestamps, dashboard timestamps, and cache state. Return formatting details are absent, but with no output schema and no parameters there is little else an agent needs to call it.

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 tool takes zero parameters (schema coverage 100%), so the baseline is 4 per the rubric. There is no argument syntax to explain, and the description correctly implies a no-argument call.

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 concrete outputs (last-made/last-read timestamps for each digest and the dashboard) and the backing source (meta.json files), plus the server's cache state. That is specific enough to separate it from every sibling (find_packages, build_failures, overview, etc.), none of which are status/freshness tools. It lacks a crisp verb like 'report' or 'show', but the resource and scope are clear.

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 reach for this tool versus siblings such as overview or needs_attention, and no exclusions or prerequisites. The agent must infer from the description alone that this is a freshness/cache inspection call.

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 and openWorldHint, so the description only needs to add context. It adds the result ordering rule and the fact that each result carries a status label, but says nothing about truncation behavior beyond the schema's limit, case sensitivity, or how statuses are computed.

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 dense sentence with no filler; the match strategy and return payload are front-loaded where an agent will read them.

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 usefully enumerates what comes back (name plus status categories). For a two-parameter read-only search this is largely sufficient; only edge-case behavior like empty results or case sensitivity is unstated.

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%, so baseline is 3; the description earns an extra point by explaining the matching precedence for 'query' (exact → starts-with → contains), which the schema's 'Part of a name' does not convey. The 'limit' parameter is left to the schema, which documents it fully.

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), a specific resource (nixpkgs packages), and even the match strategy and returned fields. It does not explicitly distinguish itself from the sibling 'package' tool (likely a single-package detail lookup), so it falls just 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?

The match ordering (exact, then prefix, then contains) implies how to phrase a query, which is implicit usage guidance. However, there is no explicit statement of when to use this versus 'package' or 'needs_attention', 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 cover the read-only/open-world safety profile, and the description adds genuinely new behavioral context: this is a derived hourly PR-digest view, and each issue kind carries different derived fields (hydra verdicts vs. update status). That provenance is useful and non-obvious, though the phrasing 'the PR digest, hourly' is terse.

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?

Purpose is front-loaded in the first clause, which is good, but the remainder is a single dense sentence with parenthetical chains ('builds: a candidate to close; failing; waiting; removed; ...') that is harder to parse than it needs to be.

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 and all five parameters documented in the schema, the description supplies enough context about data provenance and field semantics for correct invocation; missing only explicit sibling routing.

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%, so the baseline is 3, but the description goes further by explaining what verdict values mean in context ('builds: a candidate to close', 'whether nixpkgs has the version asked'), adding semantic meaning beyond the flat enum list.

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 ('Search nixpkgs' open issues by title') and immediately scopes it by the two issue kinds the tool covers. It does not name the nearest siblings (build_failures, update_attempts) to say how it differs from them, which keeps it below 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?

Usage is implied by the descriptions of the two kinds and their fields, but there is no explicit when-to-use or when-to-prefer-a-sibling guidance despite overlapping siblings like build_failures and update_attempts being present.

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 and openWorldHint, and the description adds real context beyond them: cross-parameter behavior (maintainer/team silently widen results to include canMerge PRs), the stagingNext forecast semantics, and that unsupported query words are refused with a query.page link returned. No auth or rate-limit notes, but the behavioral picture is substantially richer than the annotations alone.

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?

Purpose and the all-of-nixpkgs caveat are front-loaded, which is good, but the three sentences are long and clause-heavy, and much of the query grammar (is:, on:, team:, by:, refused sort:/age:) duplicates what the schema already says. Trimming the restated query syntax would make it tighter without losing information.

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 7-parameter, all-optional, no-output-schema tool, the description covers defaults (limit 50, kind any), the narrowing strategy, and cross-parameter side effects, and hints at the response shape via 'the answer's query.page'. What is missing is any statement of what a single package entry contains, which matters since no output schema exists.

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%, so the baseline is 3, but the description adds semantics the schema does not encode: the interaction where maintainer/team also surface open mergeable PRs, and the 'instead of the others' relationship of query to the filter parameters. That justifies going above baseline, though most per-parameter detail is a restatement of 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?

Names a specific resource and scope: 'packages that need attention, as nixkeeper's dashboard counts them', and enumerates the concrete categories (failing, outdated, vulnerable, backport) that define the set. That framing separates it cleanly from siblings like build_failures, vulnerabilities, or find_packages, which each cover only one slice.

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 explicit operational conditions: without maintainer/team/list you get all of nixpkgs (thousands), so narrow with kind; with a maintainer or team you additionally get mergeable PRs. It also states the query parameter is an alternative to the filters. It stops short of naming sibling tools to use instead, so not a 5.

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 and openWorldHint=true, so safety is covered. Beyond that, the description does real work by characterizing the response as counts plus notable exemplars ('how many ... the newest and longest-standing of each', 'blocking the most builds', 'grouped'), which with no output schema is the only signal about what the call returns. It does not mention data freshness or cost, but the aggregation 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 scope ('All of nixpkgs at a glance'), followed by a semicolon-delimited inventory of metrics. Dense but each listed category earns its place by defining the dashboard's coverage. Slightly list-heavy, but nothing 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?

With no output schema and no parameters, the description carries the burden of explaining what comes back, and it largely does so by enumerating the metrics and the notable-item pattern. The main omission is guidance on how this aggregate relates to the sibling tools that cover the same categories in detail. Given the low structural richness of the tool, coverage is close to sufficient.

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 tool takes zero parameters, so there is nothing to document and the baseline is 4. The description adds no parameter information because none exists, which 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?

States a clear purpose: an aggregate 'all of nixpkgs at a glance' dashboard, and enumerates the specific metrics it surfaces (outdated, failing builds, vulnerabilities, blocking dependencies, recent fixes). An agent can tell this is the summary view rather than a per-package lookup. It stops short of naming which siblings it supersedes, so differentiation from the many overlapping category tools (build_failures, vulnerabilities, needs_attention) is left implicit.

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?

'At a glance' implies this is the entry-point summary, and the enumerated contents imply it aggregates what siblings expose individually, but the description never states when to use this versus find_packages, build_failures, or vulnerabilities. No exclusions, no prerequisites, no ordering guidance is given. Usage is only implied by the aggregate framing.

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 and openWorldHint=true, so the safety profile is covered. The description adds meaningful context about data provenance and freshness (Repology, hourly digests, Hydra last-built timestamps, forecasts like stagingNextBreaks) that goes beyond annotations, but says nothing about whether the call is expensive or how stale data can be.

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?

It is front-loaded correctly with the core purpose in the first clause, and the semicolon list does group related fields. However the whole description is a single sprawling sentence that is hard to parse, and the dense enumeration could have been shortened with a clearer hierarchy.

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, this description is the only source of return-value information, and it enumerates the returned fields thoroughly (builds, PRs, CVEs, maintainers, staging forecasts). The main gap is that it never routes the agent from find_packages to this tool or states prerequisites.

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%, so the schema already documents both parameters, including the attribute syntax and the python3Packages alias. The description adds no format or edge-case detail about name or repology beyond what the schema provides, so 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 opening clause states the resource precisely ('one nixpkgs package') and the scope ('everything nixkeeper knows'), which an agent can distinguish from aggregate siblings like overview or needs_attention. It never names a verb (get/fetch/detail), but the lookup intent is unambiguous from the description and the single required name parameter.

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 and no sibling is named as an alternative. The reader must infer that find_packages searches while this one details a single package; the relationship is never stated.

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 and openWorldHint, so the safety profile is covered. The description adds genuinely useful context beyond that: the data is digest-derived and refreshed hourly, and the values are the digest's own judgements rather than raw GitHub state. It does not discuss pagination or result ordering beyond what the schema says.

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?

Front-loaded with the verb and resource, then the return semantics. It is one long colon-and-parenthetical sentence, which is dense but every clause carries information; only the trailing 'maybe its fix' aside is loose.

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 12 optional parameters and no output schema, the description does useful work by naming the result fields the caller will receive (buckets, state, merge-bot eligibility, duplicate flags, Hydra failures). Combined with annotations covering read-only behavior, an agent has enough to call it correctly.

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 the schema already documents all 12 parameters including enum meanings. The description largely restates those same lists (buckets, merge bot) and only mildly enriches the concept of 'state' as a comparison with current nixpkgs. Baseline 3 applies when the schema carries the load.

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 — 'Search nixpkgs' open pull requests' — scoped to the hourly PR digest, and enumerates the judgement fields it returns. It is clearly distinct from siblings like issues or find_packages by resource, though it never names an alternative 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?

Usage is only implied: the parameter list (bucket, state, can_merge, blocks_bot) suggests the triage scenarios it supports, but there is no explicit 'use this when / use X instead' guidance or statement of prerequisites. The agent must infer the intent from the field inventory.

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 and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context the annotations do not: the data is a digest refreshed every 3 hours, and single-package queries additionally surface queue position and next retry estimate. It does not address auth, rate limits, or how the many filters combine.

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?

It is a single compact sentence, front-loaded with the data source, with no filler. The semicolon-clause structure is dense and slightly run-on, and the absence of a leading verb makes the action itself less immediately scannable, keeping it short of a 5.

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 usefully enumerates what a result carries (outcome, versions, PR, failure reason with log excerpt, plus queue/retry for a single package) and notes the 3-hourly refresh. Combined with complete schema coverage for all six filters and read-only annotations, this is nearly everything an agent needs, though it never explains default behavior or how filters interact.

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%, so the baseline is 3. The description adds genuine meaning for the `package` parameter by explaining that querying one attribute also yields the bot's queue placement and expected retry time, which the schema's 'One attribute, as the bot names it' does not convey. The other five parameters (limit, since, reason, outcome, search) are left entirely to 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?

The description identifies the specific resource (nixpkgs-update / r-ryantm's latest attempt per package, the 3-hourly digest) and what it contains, so an agent can infer this tool queries the update bot's attempt records. It lacks an explicit verb (it reads as a data dictionary entry rather than 'Get...') and never contrasts itself with siblings like build_failures or pull_requests, 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 when-to-use guidance, no condition that selects this tool over siblings such as build_failures or needs_attention, and no mention of prerequisites. The only hint of a usage mode is the incidental note that queries for one package also return queue position, which is not framed as 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 and openWorldHint, so the safety profile is covered. The description adds real context beyond that: data provenance (NixOS tracker + OSV advisories), update cadence ('hourly' digest), and result ordering ('worst first'). The phrasing about the digest is murky, keeping it from a 5.

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?

Everything is packed into a single run-on sentence with heavy parenthetical nesting, and phrases like 'the vulnerabilities digest, hourly' are hard to parse. The core purpose is front-loaded, but the structure could be considerably cleaner.

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 helpfully pre-announces what each record contains (issue, severity, affected versions, master and release-branch status), which compensates for the missing return documentation. Combined with the query modes and default ordering, an agent has enough to call it correctly, though edge cases (e.g., combining severity with package) are unaddressed.

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 the baseline is 3. The description adds value above baseline by describing default behavior when no parameters are supplied (CVEs affecting packages, worst first) and by mapping the query modes onto the parameters. It does not, however, explain parameter interaction or precedence explicitly.

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 precisely (CVEs from the NixOS security tracker plus OSV advisories for language packages) and enumerates the three query modes: one package's CVEs, one CVE/advisory id, or CVEs affecting a package sorted worst-first. This clearly separates it from siblings like issues or build_failures. It stops short of naming any sibling tool, so it earns a 4 rather than 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?

The three query modes imply when each parameter applies, but there is no explicit when-to-use/when-not guidance and no routing to or from alternatives like issues or find_packages. Usage is inferable but left to the agent to reconstruct.

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