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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true. The description adds meaningful context beyond that — the bump-rights permission requirement and the queued precondition — but omits what happens to displaced builds and the failure behavior when the build is not queued.

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 short sentence with the action and the key constraint front-loaded; no 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?

An output schema exists, so return values need not be explained. However, for a non-idempotent mutation with an under-documented required parameter, the description lacks failure modes, displaced-build behavior, and instance-defaulting guidance that the agent would need.

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 only 50%: 'instance' is documented in the schema but 'build_id' carries only a title and minimum of 1. The description says nothing about either parameter, so it fails to compensate for the coverage gap.

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 with scope: 'Move a queued build to the front of the queue.' An agent can distinguish it from cancel_build/restart_build/get_queue by the queued-only, front-of-queue semantics, though no sibling is named 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?

The parenthetical '(needs bump rights)' gives a prerequisite, and 'queued' implies the applicable state. But it never says what to do for non-queued builds or points to restart_build as the alternative for already-running/complete builds.

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?

The annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the risk profile is largely covered by structured data. The description adds real value by disclosing the permission prerequisite and the human-confirmation requirement, but says nothing about what happens to build artifacts, logs, or in-flight jobs once cancelled.

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 sentence with the action front-loaded and two parenthetical constraints carrying the safety-critical information. Nothing is padded and nothing needs to move earlier.

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 two-parameter destructive tool this covers purpose, permission requirement, confirmation workflow, and the output schema handles the return value. The only material omission is the post-cancel effect on the build itself, which is left to the annotations to imply.

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 50%: 'instance' is documented in the schema as falling back to the configured default, while 'build_id' has no description but is self-evident from the tool name and the integer/minimum constraint. The description itself adds no parameter meaning, which is acceptable here only because the remaining gap is small.

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 verb (cancel) applied to a specific resource (build) and narrows the scope to 'queued or running' builds. That verb is cleanly distinguishable from sibling mutations like restart_build and bump_build, so an agent can select it without opening the schema.

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 supplies two concrete operating conditions that govern invocation: the caller needs cancel rights, and the agent should confirm with the user before acting. It does not explicitly say when to cancel versus restart a build, so no exclusions or named alternatives are given.

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 safety (readOnly, idempotent, non-destructive), so the description adds real value on top: what the default step selection returns, how "all" scales, and the diagnostic behavior where failed steps name the dependency behind "dependency failed". That last detail is non-obvious output semantics an agent could not get from the schema.

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 resource and returned fields, then immediately the parameter that needs explanation. Nearly every sentence carries information; only the line-broken layout makes it slightly more sprawling than needed.

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 detail is optional, yet the description still summarizes content and adds the one behavior (dependency-failure naming) that matters for interpreting results. Missing coverage of steps="none" and no cross-reference to get_build_log are the only residual gaps.

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 50%, so the description must carry weight for the undocumented parameters, and it does: it explains steps="relevant" vs "all" and implies that recent_steps controls the "newest few" shown. The steps="none" value is never explained, leaving one gap in a three-value enum.

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 and enumerates what the response contains (status, timing, derivation, outputs, products, metrics, steps), which is far more informative than the bare name. It does not explicitly differentiate itself from get_build_log or get_job, so sibling routing is left to inference.

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 gives clear usage guidance for the steps parameter, including the default and the cost trade-off ("large for big closures"). It says nothing about when to call this instead of get_build_log, get_job, or get_queue, so tool-selection guidance is only implied.

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 this as read-only, idempotent, non-destructive, and open-world, so the safety profile is covered. The description adds that only the tail of the log is returned and that step logs are supported, but it omits behavioral details such as truncation behavior, permissions, or how missing logs are handled.

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 a single front-loaded sentence with no wasted wording. It immediately communicates the core action and the optional step-level scope.

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?

Given the output schema and rich annotations, the description covers enough for an agent to understand this as a log-tail retrieval tool. The main missing piece is explicit routing guidance relative to sibling build tools.

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 description maps naturally to tail_lines ('last lines') and step ('one of its build steps') and adds the useful failed-dependency example. However, with only 50% schema description coverage, it does not explain instance or give details about tail_lines limits/defaults, so it only partially compensates for the schema gap.

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 specific verb and resource: retrieving the last lines of a build log or one of its step logs. It clearly distinguishes log retrieval from general build inspection, though it does not explicitly name sibling tools such as get_build.

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 phrase 'or of one of its build steps (e.g. the failed dependency)' implies when step-level logs are useful, but the description does not explicitly state when to use this tool versus get_build or other alternatives. Usage context is present but mostly left to inference.

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 read-only, idempotent, non-destructive, open-world behavior, so safety is covered. The description adds return scope (inputs, build counts, builds) and status-filter semantics, but it omits pagination/limit behavior and any auth or rate-limit context.

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 action and returned data, then a compact status legend. There is no filler or repetition, and the status definitions earn their place by clarifying the enum.

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 needn't be fully explained, and annotations cover the safety profile. Still, for a 4-parameter tool with low schema coverage, the description omits limit/pagination semantics and does little to distinguish eval_id or instance, leaving meaningful gaps.

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 low at 25%, with only 'instance' documented in the schema. The description partially compensates by defining the status enum meanings ('failed' = finished but not succeeded, 'queued' = not finished yet), but leaves 'limit' and 'eval_id' undocumented beyond their names and schema types.

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 opens with a specific verb and resource ('Get an evaluation') and enumerates the payload ('inputs, build counts by status and its builds'), so an agent knows this is a single-evaluation read. It does not explicitly contrast with siblings like list_evals or get_build, 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?

It explains the status filter and its values, which guides filtering behavior. However, it never states when to choose get_eval over list_evals/get_build or any prerequisite; usage is only implied by the required eval_id and the verb 'Get'.

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 destructiveHint=false, so the safety profile needs no restating. The description does add genuine behavioral context by stating that both an any-status build and the latest successful build are returned. It stays silent, though, on what happens when the job has no evaluation or no successful build, which matters for a tool that promises two results.

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 tightly packed sentence with the retrieval scope front-loaded and no filler. It is slightly ambiguous about whether the two builds are returned together from one call, 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?

With rich annotations and an output schema present, the description doesn't need to explain return formatting, and it correctly avoids doing so. Still, for a tool that fetches two differently-scoped builds, it should say whether both are returned in one response and what happens when one target 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?

Schema coverage is 60%, so the schema carries most of the burden and already documents job, system ('Only for latest_successful'), and instance. The description's only parameter-relevant contribution is the implicit 'latest successful build' concept that justifies the system parameter, which largely duplicates what the schema already states; project and jobset semantics are untouched.

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 verb and resource (get a job's build) and scopes it to two retrieval targets: the newest evaluation's build of any status and the latest successful build. That framing distinguishes it reasonably well from get_build (a specific build) and get_jobset (a whole jobset), 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?

Usage is only implied: the '(any status)' vs 'latest successful build' contrast hints at two distinct retrieval intents, which helps an agent pick this over get_build. However, there is no explicit when-to-use/when-not guidance and no mention of the obvious alternatives (get_build, get_jobset) for drilling into a single build or a whole jobset.

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 destructiveHint=false, so the safety profile is covered. The description adds that errors are included in the response and that recent evaluations are returned, but it does not say what happens if the jobset is missing, how many evaluations are included by default, or whether the response is paginated. With annotations carrying the safety burden, this is adequate 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?

The description is a single front-loaded sentence with no filler, immediately stating the verb, resource, and returned data. Every clause earns its place by identifying what the call retrieves.

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 and annotations covering safety and idempotency, so the description needn't explain return format or side effects. However, with four parameters at 25% schema description coverage, the description is incomplete regarding the recent_evals limit and the required project/jobset scoping. It gives the gist but leaves parameter behavior to inference.

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 25%: only the 'instance' parameter documents its default in the schema. The description mentions 'most recent evaluations' but does not explain the recent_evals parameter's default of 5 or maximum of 20, and says nothing about the required project and jobset parameters or their naming patterns. With low schema coverage, the description should compensate but 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 names a specific verb and resource ('Get a jobset') and enumerates what is returned: configuration, evaluation state and errors, plus recent evaluations. This clearly distinguishes it from list-oriented siblings such as list_evals or get_eval, though it does not explicitly contrast itself with get_job or get_project.

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 alternatives like list_evals, get_eval, or get_job. The description implies a detail-fetch use case but gives no exclusions, prerequisites, or 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 this as read-only, idempotent, open-world, and non-destructive, so the safety profile is clear. The description adds useful detail about returned content—project settings, per-jobset errors, and last evaluation—which goes beyond what annotations provide. It does not mention auth requirements or rate limits, but with annotations present the bar is lower.

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 a single, front-loaded sentence with no filler. Every clause ('settings', 'state of each of its jobsets', 'errors, last evaluation') adds meaningful scope 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?

An output schema exists, so return values need not be fully explained, and annotations cover the safety profile. The description states the core scope well for a read-only getter; the main remaining gap is not routing the agent to sibling tools like get_jobset or list_projects when those might be more appropriate.

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 50%: the 'instance' parameter is documented in the schema, but the required 'project' parameter has no description there or in the tool description. The description does not clarify the project identifier format or how instance selection affects results, so it fails to compensate for the coverage gap.

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 uses a specific verb ('Get') and resource ('one project's settings and the state of each of its jobsets'), making the scope clear. It implicitly distinguishes itself from list_projects by specifying 'one project', but does not explicitly name any sibling tools for 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?

Usage is implied: this tool is for inspecting a single project's settings and jobset health. However, there is no explicit guidance on when to use it versus list_projects, get_jobset, or put_project, and no exclusions or prerequisites are 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 this as a read-only, idempotent, non-destructive operation. The description adds useful behavioral context beyond that: the queue is ordered highest priority first, and the result includes jobset-level size and currently running builds.

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 earns every clause by naming the queue, its ordering, its jobset breakdown, and the running-builds component.

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 and annotations covering safety, the description needs only to establish purpose and scope. It does that well, though the unexplained limit parameter is a small remaining gap 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 only 50%: instance is documented in the schema, but limit is not. The description does not explain what limit controls, whether it truncates the queue, or how ordering interacts with it, so it fails to compensate for the schema gap.

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 specific verb and resource (get the build queue) and enumerates what is returned: queue order, size by jobset, and currently running builds. It is clear, but it does not explicitly distinguish itself from sibling tools like get_build or get_jobset.

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 offers no when-to-use guidance, no exclusions, and no alternatives. An agent must infer that this is the queue-inspection tool from the name 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 declare read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds two genuinely useful behavioral facts not in the annotations: results are newest-first and paginated one page at a time. It does not disclose page size, total counts, or what happens past the last page, keeping it at a solid but not rich 3.

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; scope, ordering, and pagination are front-loaded in one clause. Every element 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 simple read-only list tool with an output schema and full annotation coverage, the description supplies the key behavioral facts (ordering, pagination) an agent needs. Minor gaps remain around page size and boundary behavior, but nothing essential to invoking it 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?

Schema description coverage is only 25% (only 'instance' is documented in the schema), so the description must compensate. It mentions 'jobset' and implies the 'page' parameter via 'one page at a time', but adds nothing about project scoping or page-size semantics. Baseline 3 for a partially self-documenting parameter set.

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 ('List a jobset's evaluations') plus scope and ordering, so an agent can distinguish it from get_eval and the other list_* tools. It stops short of explicitly naming sibling alternatives, but the operation is unambiguous.

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: 'a jobset's evaluations' tells the agent it must supply a jobset, and 'one page at a time' hints at paging. There is no explicit guidance on when to use this versus get_eval or search, nor any prerequisite/context statements.

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=false, so the safety profile is covered by structured data. The description adds real content beyond that by disclosing what the result contains (the default instance, per-instance write-login capability), which annotations cannot express.

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 the resource first and the two returned attributes immediately after. Nothing is redundant or restates the tool name.

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 per-field return documentation is unnecessary, yet the description still pre-summarizes the two most decision-relevant fields. For a zero-argument, read-only listing tool with rich annotations, nothing an agent needs in order to call it correctly 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?

The input schema has zero properties, so there is no parameter semantics to explain; the baseline for a no-parameter tool is 4. The description correctly implies the call takes no arguments by describing only the resource being listed.

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 ('List') and resource ('configured Hydra instances') and goes further by naming the two facts returned about each: which one is the default and whether it can log in for write tools. No sibling (cancel_build, get_project, list_evals) overlaps with Hydra instance discovery, so it is unambiguously distinct.

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 phrase 'whether each can log in for write tools' implies a pre-flight use case — checking write capability before invoking a mutating tool — but the description never says when to call this versus just calling a write tool, nor does it state any prerequisites or exclusions. Usage must be inferred rather than read.

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, non-destructive and open-world, so the safety profile needs no repetition. The description adds that jobsets are bundled into the result, which is genuine extra information, but says nothing about ordering, pagination, or failure behavior for an unknown instance.

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 short sentence that front-loads the action and resource with zero padding. Nothing could be removed without losing 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 and annotations are rich, so the description needn't explain return values or safety. Still, for a listing tool with an open-world instance selector, it gives no hint about result scope or how the instance affects what is returned.

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 `instance` parameter is already documented as 'omitted uses the default'. The description adds nothing about the parameter, so the baseline of 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 ('List the projects of a Hydra instance') and adds a useful scope note that jobsets are included. It is distinguishable from get_project (single project) by the plural 'projects', though it never explicitly contrasts with siblings.

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?

No statement of when to use this versus get_project, list_instances, or search. The agent must infer that this is the enumeration entry point and that list_instances may be needed first to obtain a valid instance name.

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 destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is structured. The description does add value by warning about confirmation and by scoping cancel to queued builds (not running ones), but it says nothing about what happens to running builds during restart, whether restart is bounded, or the effect on the queue ordering.

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 action set, followed by the one safety-critical caveat. Nothing redundant; every clause carries 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?

With annotations covering safety and an output schema present, the description need not explain returns. It covers actions and the destructive-cancel warning, leaving only sibling differentiation and the running-vs-queued build nuance under-specified.

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 only 33% (only 'instance' is described), so the description must carry the action semantics. It does partially: the four enum values map to restart-failed, restart-aborted, cancel queued builds, and bump to front. But it doesn't explain how 'instance' interacts with the default, nor whether restart applies to the whole eval or specific builds.

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 specific verbs and the resource scope: restart an evaluation's failed/aborted builds, cancel queued builds, or bump them. It is clear what the tool does, but it never distinguishes itself from the per-build siblings restart_build, cancel_build and bump_build, so an agent must infer that this is the evaluation-level bulk variant.

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 'confirm with the user first' instruction gives real guidance for the cancel action, and the action list implies the four usage modes. But there is no statement of when to pick manage_eval over restart_build/cancel_build/bump_build, which is the main selection decision an agent faces here.

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?

Beyond annotations, it discloses that this is a partial update ('others keep their values'), requires project ownership or admin, and lists defaults for new jobsets. These are valuable behavioral details, though it does not discuss conflict handling or other operational limits.

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 three short paragraphs with no wasted language. The create/update purpose, branch selection, permissions, and defaults are front-loaded and easy to scan.

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 15-parameter mutation tool, the description covers the core invocation paths, permissions, and defaults. It still leaves many optional parameters dependent on sparse schema descriptions, so an agent may need to infer behavior for fields like state and scheduling_shares.

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 15 parameters and only 47% schema description coverage, the description adds useful meaning for the flake-vs-legacy branch and for create-vs-update semantics. However, many optional fields such as state, visible, email_notifications, scheduling_shares, and description are left to the schema alone, which is a clear gap for a tool of this size.

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 specific verb and resource: 'Create a jobset, or change the given fields of an existing one.' It also clarifies that unspecified fields keep their values, which is a meaningful distinction between create and partial update.

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 clear context for creation variants ('Give `flake` for a flake jobset, or nix_expression_input/path plus inputs for a legacy one') and states the required permission level. It does not explicitly name sibling alternatives such as get_jobset or put_project, so it falls short of full when-to-use/when-not 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 idempotentHint=true, destructiveHint=false and openWorldHint=true, but the description adds two things not in annotations: the per-mode permission requirements and the partial-update contract ('others keep their values'). It stops short of saying what happens on a name collision or what the response contains, but for an annotated tool this is solid added context.

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 short sentences with no waste: the create-or-partial-update behavior comes first, the permission requirement second. Every clause 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?

The output schema means return values need no explanation, and the auth/idempotency picture is reasonably covered. But for a 7-parameter mutation with 14% schema coverage, the description leaves the meaning of the optional fields and the null-vs-omitted distinction entirely unspecified.

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 14% (only `instance` is documented), so the description must carry the burden, and it does not. Six of seven parameters (`enabled`, `visible`, `homepage`, `description`, `display_name`, `project`) are never mentioned, and it is unclear whether passing null leaves a field unchanged or clears it.

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 and, importantly, clarifies the upsert semantics: create a new project or modify only the given fields of an existing one. An agent can tell this is a write tool on the `project` resource rather than a read like `get_project`/`list_projects`, though no sibling is named 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?

Gives the authorization prerequisites for each mode (create-projects role to create, project ownership to edit), which is real usage context. However, it offers no guidance on when to prefer this over `put_jobset`/`get_project` or on what to do when the project already exists.

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 (not read-only, not destructive, not idempotent, open-world). The description adds value beyond them by disclosing the permission requirement ('restart rights') and the state constraint (only finished builds), both operationally important. It stops short of saying whether prior logs/results are discarded or a new build ID is produced.

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 verb and the key constraint front-loaded and no wasted wording; the terseness borders on under-specification but stays efficient.

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 not be explained, and the auth prerequisite is stated. Still missing are the consequences of re-queueing (fate of prior build artifacts/logs, whether a new build id is returned) that matter for a mutation in a CI system.

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 50%: the instance parameter is documented in-schema, but build_id has no description in either schema or prose. The description adds no parameter-level meaning at all, so it does not compensate for the gap.

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: 'Re-queue a finished build'. The 'finished' qualifier implicitly distinguishes it from cancel_build and bump_build, which act on other build states, though no sibling is named 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?

'needs restart rights' gives a prerequisite and 'finished build' implies an eligibility condition, but there is no explicit when-to-use-versus-alternatives guidance (e.g., when to restart vs. trigger a fresh build or bump).

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, so the safety profile is covered. The description adds nothing beyond purpose: no result ordering/ranking, no cap on hits, no statement about whether the search spans one Hydra instance or all configured ones.

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 names the covered entities before the match fields. No filler, no repetition of schema or annotations.

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 all entity types are enumerated. Given a two-parameter read-only tool, the description covers what an agent minimally needs to select and 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?

Schema coverage is 50%: the 'instance' parameter is documented ('omitted uses the default'), but 'query' carries only length constraints. The description partly compensates by saying the query matches names, output paths and derivation paths, which is genuinely useful, though it omits the 2-character minimum and the per-instance scoping.

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 (search) plus the four resource types covered (projects, jobsets, jobs, builds) and the match fields (name, output, derivation path). That is far more informative than the bare name 'search', but it never distinguishes this tool from the many list_*/get_* siblings that also surface projects and builds.

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?

No statement of when to prefer this tool over list_projects, list_jobsets, or get_build, and no note about the single-instance scoping. The parenthetical match fields hint at free-text lookup, but the agent must infer that on its own.

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 declare non-read-only, non-destructive, non-idempotent, open-world, so the description's added value is auth requirements ('needs restart rights') and the deduplication behavior that 'force' bypasses. That is meaningful context beyond the annotations. It doesn't say whether the call returns immediately or waits on the evaluation, which keeps it from 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?

Two short sentences, no filler, with the core action front-loaded and the permission caveat and force semantics following immediately. Every clause carries 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?

With annotations present and an output schema declared, the description covers the action, the permission requirement, and the key parameter nuance. The main residual ambiguity is what 'soon' concretely means (queued vs. immediate execution) for a tool whose annotations already say it is not idempotent.

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 only 25% (just 'instance'), so the description must carry weight, and it does explain the one non-obvious parameter: 'force re-evaluates even if inputs are unchanged.' project and jobset are self-describing by name and pattern, so the remaining gap is small.

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 verb and resource ('evaluate a jobset') and clarifies the trigger is asynchronous/deferred ('soon'), which separates it from siblings like restart_build, bump_build, and manage_eval. It does not explicitly name which sibling to prefer, so it stops short of 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 parenthetical 'needs restart rights on the project' gives a real precondition for use, and the 'force' note hints at the re-evaluation case. But there is no explicit when-not guidance or pointer to an alternative (e.g., bump_build vs. restart_build) for triggering work.

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