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 declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuine context beyond them: the data is a PR digest refreshed hourly, and it explains the meaning of the derived hydra:/update: fields and their value sets. It stops short of describing return format or pagination behavior.

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, with the core purpose front-loaded before the per-kind detail. The second sentence is dense and its grammar is awkward ('what Hydra builds now say'), but no sentence 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?

For a read-only, open-world search tool with all five parameters fully documented in the schema and no output schema, the description supplies the missing conceptual layer: what the two issue kinds carry and how the derived fields should be read. The main gap is the absence of any routing guidance relative to the overlapping siblings.

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 every one of the five parameters (kind, limit, search, package, verdict) is already documented with enums spelled out. The description's mention of 'builds: ... failing; waiting' partially overlaps the verdict enum but adds no format or syntax detail beyond the schema. 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: 'Search nixpkgs' open issues by title', with the data source (the PR digest) identified. It splits the resource into two kinds (build-failure vs update requests), which is descriptive, but it never distinguishes itself from the sibling tools build_failures and update_attempts that appear to cover the same ground.

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 description of what each issue kind contains and the note that the digest is hourly, but there is no explicit statement of when to choose this tool over build_failures or update_attempts, and no prerequisites or exclusions. No guidance on the limit/search interplay either.

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 safety is covered. The description adds real behavioral context beyond that: the exact aggregation semantics behind 'needs attention', the scale warning for unfiltered queries, and the non-obvious fact that maintainer/team queries also surface canMerge PRs. It stops short of describing ordering or result shape.

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 definition before the scoping rules, with no filler. The second sentence is dense and packs several conditions (maintainer vs team vs list, canMerge) into one clause, which costs a little readability but every element is load-bearing.

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 6-parameter, zero-required, complex aggregation tool with no output schema, the description covers what is counted, how scope changes with filters, and the scale caveat. What is missing is anything about result ordering or the shape of a returned package entry, which an agent may want when composing downstream calls.

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 and the schema already documents kind, list, team, limit, platform, maintainer. The description still adds cross-parameter meaning the schema cannot: that maintainer/team/list are mutually alternative scoping dimensions and that maintainer/team additionally triggers canMerge results.

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 precise definition of the resource: packages that need attention as the nixkeeper dashboard counts them, enumerating the qualifying categories (failing build, outdated, vulnerable, backport). This rescues a fairly vague tool name. It does not explicitly route the agent away from subset siblings like build_failures or vulnerabilities, so it stops short of full sibling differentiation.

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 explains the two operating regimes clearly: without maintainer/team/list the scope is all of nixpkgs (thousands, narrow with kind), and with a maintainer or team the result also includes mergeable PRs (canMerge). That is concrete when-to-use context. It never names an alternative sibling tool to use instead, so no explicit exclusions.

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.