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

Annotations already declare readOnlyHint=false and destructiveHint=false; the description aligns with these and adds valuable context beyond them — the ZUUL_READ_ONLY=false environment requirement is a key behavioral constraint not captured in annotations. No contradiction between description and annotations; the description augments the safety profile with an operational prerequisite.

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 appropriately sized and well-organized: a front-loaded purpose sentence, a one-line prerequisite, then a clean Args list. Every line earns its place — no filler, no repetition of schema fields, and the parameter list is structured for easy scanning.

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 an 8-parameter mutation tool with an output schema present, the description is complete: it covers purpose, environmental requirements, and every parameter's semantics, defaults, and optionality. The output schema handles return values, so no additional description of results is needed.

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?

Despite 0% schema description coverage, the description fully compensates by documenting all 8 parameters with semantics ('project: Project name (e.g. org/repo)'), defaults ('count: Failed builds to hold (default 1)'), units ('node_hold_expiration: Seconds... default 86400 = 24h'), and optionality ('change: Change filter (optional)'). This adds substantial meaning beyond the bare 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 states a specific verb+resource ('Create an autohold request') with the precise purpose: 'hold nodes after a job failure for debugging.' This clearly distinguishes it from siblings like autohold_delete, list_autoholds, and get_autohold, which serve different lifecycle actions on the same resource.

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 conveys when to use the tool ('after a job failure for debugging') and states a critical precondition ('Requires ZUUL_READ_ONLY=false'). It names the context clearly but doesn't explicitly exclude alternatives (e.g., viewing existing holds via list_autoholds), though the create-vs-read distinction is fairly implicit.

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 and readOnlyHint=false. The description adds valuable context by requiring ZUUL_READ_ONLY=false for write access and specifying that autohold_id should be obtained from list_autoholds. This clarifies operational prerequisites and dependencies beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise and well-structured: a single-line purpose, a requirement, and a clean argument list. Every sentence adds essential value with no filler or redundancy.

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 delete operation with two parameters and an output schema, the description covers all necessary invocation details: purpose, prerequisite, and parameter sources. The destructive nature is already captured by annotations, making this sufficiently complete for an agent to use 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 0%, so the description carries the full burden for parameter semantics. It explains autohold_id as the ID from list_autoholds and notes that tenant defaults from the environment, adding meaningful guidance beyond the schema's bare type definitions.

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 clearly states 'Delete an autohold request' with a specific verb and resource, distinguishing it from sibling tools like autohold_create and list_autoholds. The purpose is unambiguous and action-oriented.

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 explicit guidance on when to use this tool versus alternatives. It mentions a prerequisite (ZUUL_READ_ONLY=false) but does not provide context for when deletion is appropriate or when to prefer other autohold-related tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes further by revealing that the tool runs diagnose_build(brief=True) in parallel, returns a compact classification summary, and enforces a max of 20 UUIDs. This adds behavior context beyond the annotations, but it does not discuss error handling or partial failure behavior, which would be valuable.

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 tightly structured: it opens with the core purpose, then explains the execution model, then gives usage alternatives, and finishes with an Args list. Every sentence earns its place, and the content is front-loaded. No padding or redundant statements.

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 tool's batch nature and the availability of an output schema, the description covers all essential context: what it does, how it works, when to use it, parameter constraints, and return style. The presence of an output schema means detailed return field documentation is unnecessary here. The description is complete for selecting and invoking this tool 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 0%, so the description must carry parameter semantics. It does so effectively: 'uuids: List of build UUIDs to diagnose (max 20)' and 'tenant: Tenant (default from env)' add constraints and defaults not present in the raw schema. This provides actionable meaning for both parameters, though it could be slightly richer (e.g., UUID format hints).

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: 'Classify multiple failed builds in one call — returns a triage table.' It clearly distinguishes from the sibling diagnose_build by stating 'Use instead of calling diagnose_build N times when triaging multiple failures.' This explicitly identifies the tool's unique role in the batch context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance: 'Use instead of calling diagnose_build N times when triaging multiple failures.' It also explains the mechanism (runs diagnose_build(brief=True) in parallel) and implies the single-build alternative is diagnose_build, giving clear context for selection.

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?

Discloses important behaviors beyond annotations: path semantics (no path lists top-level, trailing '/' lists subdir, file path fetches content), a 512KB size limit, max_lines behavior, and direct_log_url skipping build metadata fetch. These details are essential for correct invocation.

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 compact and well-structured: a one-sentence overview, a short mode breakdown, and a bulleted Args list. Every sentence provides necessary information without redundancy.

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?

Covers all functional modes, parameter semantics, size limits, and alternatives. With an output schema present, return values are already specified, so the description is complete for tool selection and 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?

Despite 0% schema description coverage, the description explains every parameter (uuid, tenant, path, url, max_lines, direct_log_url) with concrete meaning and example format. It fully compensates for the schema's lack of description and adds practical context.

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-resource pair: 'Browse or fetch files from a build's log directory.' It clearly explains the three modes (top-level listing, subdirectory listing, file content fetch) and distinguishes itself from get_build_log by mentioning it as an alternative for filtered reads.

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?

Explicitly states when to use get_build_log instead for filtered reads, and provides usage patterns for path handling and direct_log_url. It does not exhaustively cover all sibling alternatives, but the guidance is clear and practical.

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 idempotentHint=true, indicating a safe, idempotent operation. The description adds useful behavioral context: 'Re-auth happens automatically via Kerberos if the session expired.' This goes beyond the annotations and provides insight into session management, which is valuable for the agent.

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 extremely concise: two short sentences in total, front-loaded with the primary purpose. Every sentence adds value—the first states the function, the second provides usage context and an important behavioral detail. No filler or redundant text.

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 tool's simplicity (zero parameters) and the presence of an output schema, the description is complete. It covers the purpose, usage, and an important behavioral trait (auto re-auth). There is no missing info that would impede an agent from selecting or invoking the tool 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?

The tool has zero parameters, so there is no parameter info to explain. Per the rubric, a baseline of 4 is appropriate for zero-parameter tools. The description does not need to describe parameters, and the schema coverage is 100% (vacuously).

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 clearly states the tool's function: 'Test Zuul API connectivity and auth status.' This is a specific verb+resource combination that distinguishes it from sibling tools like list/get operations. The title 'Health Check' also reinforces the purpose, making it 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?

The description provides clear context for when to use the tool: 'Use this to verify the server is reachable.' This is sufficient for a health check tool, though it does not explicitly mention alternatives. However, given the unique purpose and context signals, no exclusions are necessary.

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, and non-destructive. The description adds operational detail: 'fetches build metadata once' and runs failure analysis and JUnit test parsing 'in parallel'. This goes beyond the annotations by revealing internal execution and efficiency, though it doesn't cover error handling or edge cases.

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 succinct: a two-line pitch, a short behavior sentence, and a clear arg list. It front-loads the purpose and avoids fluff. Every sentence 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?

Given the tool's medium complexity (combination of two operations), the description covers behavior, parameters, and rationale. It doesn't discuss what happens when both uuid and url are provided or neither, but the existence of an output schema reduces the need to detail return values. Overall, sufficient for an agent to invoke 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?

With 0% schema description coverage, the description compensates by listing all four args with meaning: uuid, tenant, url (as alternative), and brief (with default and effect). This adds value beyond the bare parameter names in the schema, though some descriptions (e.g., 'uuid: Build UUID') are minimally informative.

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 clearly states it 'combines diagnose_build and get_build_test_results' to provide 'One-call diagnosis + test results'. This specific verb+resource pairing distinguishes it from siblings like diagnose_build, get_build_test_results, and get_build_failures.

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 explicitly notes this tool 'Saves a round-trip vs calling both tools separately', giving clear when-to-use guidance. It doesn't explicitly exclude use cases like 'if you only need one result, use the individual tool', but the combined-purpose framing implies it. The alt-parameter option (url vs uuid+tenant) adds useful context.

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?

While annotations already declare the tool as read-only and non-destructive, the description adds valuable context about the composite behavior (merging failure info with log grep) and the brief mode's omission of playbooks/log_context/full task details. It does not over-explain, and no contradictions exist.

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 compact and well-structured, front-loading the core value proposition followed by a clear parameter list. Every sentence contributes to understanding, and there is no redundant or filler 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?

Given an output schema exists and annotations convey safety, the description covers the main return content and behavior modes well. It could briefly mention handling of errors or when to prefer batch_diagnose for multiple builds, but these are minor gaps in an otherwise complete context.

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 schema has zero descriptions, so the description fully compensates by explaining each parameter: uuid, tenant, url (as alternative to uuid+tenant), and brief (with effect on response size). This is exactly the kind of semantic enrichment needed for schema-sparse tools.

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 clearly identifies the tool as a one-call failure diagnosis combining failure classification with log context. It explicitly distinguishes itself from siblings get_build_failures and get_build_log, making its purpose and scope 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?

It explicitly says 'Use this instead of calling get_build_failures + get_build_log separately,' providing direct guidance on choosing this over alternatives. The mention of the 'brief' mode for smaller responses also helps users pick the right option based on needs.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context by explaining the analysis methodology (computes pass/fail statistics, threshold for flaky) and parameter behaviors like limit max and tenant default, which goes beyond the structured annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear one-sentence summary, a brief paragraph on the detection logic, and a numbered Args list. It is a bit verbose due to the parameter details, but every sentence serves a purpose and is 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?

Given that the tool has an output schema, the description does not need to explain return values. It covers the purpose, methodology, all input parameters with semantics, and acknowledges defaults/limits. It does not list prerequisites or when not to use, but for a read-only analysis tool, it is sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description fully compensates by providing meaningful explanations for each parameter: job_name, tenant, project, pipeline, limit, and detail. It clarifies defaults, filters, and what the detail flag does, adding value beyond the raw 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 clearly states the tool's purpose: 'Detect flaky jobs by analyzing recent build history for intermittent failures.' It uses a specific verb ('detect') and resource ('flaky jobs'), and the method is described. This distinguishes it from sibling tools like get_job or 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 description explains what the tool does and even provides a criterion (>20% failure rate), but it does not explicitly state when to use this tool over alternatives or mention any exclusions. Usage is implied rather than directly contrasted with siblings.

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 non-destructive behavior, so the description adds no extra context beyond that. It is consistent with annotations, but it does not disclose additional behavioral traits like error handling or response specifics.

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 brief and front-loaded with the core action, followed by a compact Args list. Every sentence serves a purpose, with no redundant or irrelevant 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 simple get-by-ID tool with an output schema present, the description provides sufficient context. The annotations cover safety, the Args cover parameters, and the 'from list_autoholds' hint supplies workflow context, making the tool fully usable.

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 no property descriptions (coverage 0%), but the description's 'Args' section fully compensates by explaining both parameters: autohold_id's source and tenant's default-from-env behavior. This adds clear meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Get details') and a clear resource ('specific autohold request'), distinguishing it from sibling tools like list_autoholds. The title 'Autohold Details' reinforces the tool's unique focus.

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 implies usage context by noting that autohold_id comes from list_autoholds, but it does not explicitly state when to use this tool versus alternatives or mention any exclusions. The guidance is minimal and implied rather than direct.

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, and non-destructive hints. The description adds useful behavioral context: the output is an SVG URL, it reflects the latest buildset result, and the tenant parameter defaults from the environment. This goes beyond the annotation hints.

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 exceptionally concise: one purpose sentence followed by a structured arguments list. Every sentence earns its place with relevant details, and the purpose is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description only needs to cover purpose and parameters, which it does adequately. Minor ambiguity around the exact semantics of pipeline/branch filters remains, but the tool is simple enough that the provided details are sufficient for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, so the description must compensate. It does: project includes an example format ('org/repo'), tenant notes the env default, and pipeline/branch are described as filters. While 'filter' is somewhat vague, the added context clearly aids interpretation.

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 clearly states 'Get a status badge URL (SVG) for a project's latest buildset result' – a specific verb (get), resource (badge URL), and scope (latest buildset). This distinguishes it from sibling tools like get_build or get_status.

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 no explicit guidance on when to use this tool vs alternatives, nor does it mention exclusions. The intended use is implied by the purpose (obtaining badge URLs), but no comparison to similar status tools is provided.

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 idempotentHint=true, so the safety profile is covered. The description adds what specific details are returned (log URL, nodeset, artifacts, etc.) and the effect of the 'brief' flag, providing some value beyond annotations. No contradiction is present.

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 concise, with a clear one-line purpose then a structured Args list. Every sentence adds value—no filler or repetition. It is front-loaded with the main purpose.

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 tool is a simple read-only getter with an output schema and strong annotations, the description covers all essentials: what it returns, all parameter semantics, and the brief option. It does not need to explain return format because the 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 description coverage is 0%, so the description must fully explain parameters. It does so effectively: uuid explains full or prefix from list_builds, tenant notes default from env, url explains alternative to uuid+tenant, and brief specifies the compact response fields. Each parameter's meaning and usage is clarified.

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 clearly states the tool retrieves build details and lists specific items (log URL, nodeset, artifacts, timing, error detail). It distinguishes from siblings like list_builds (which lists builds) and get_build_failures (specifically failures). The verb 'Get' and resource 'build' are specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides some usage context by explaining that uuid comes from list_builds and that url is an alternative to uuid+tenant. However, it does not explicitly state when to use this tool over alternatives like get_build_log or get_build_failures. The guidance is implied rather than explicit.

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 idempotentHint, so safety is clear. The description adds valuable context by noting the LOGJUICER_URL configuration requirement and the parameter alternatives (url vs uuid+tenant), going beyond the annotations without contradicting them.

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 concise and well-structured: a one-sentence purpose, a requirement line, and a clean Args list with no redundant text. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description needn't explain return values. It covers the essential context: purpose, environment requirement, and parameter semantics. It lacks some usage scenarios, but for a simple tool, the essentials are covered.

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 0%, so the description must compensate, and it does excellently. It explains each parameter (uuid as build ID, tenant with env default, url as alternative to uuid+tenant), providing meaning and relationships not present in 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 clearly states the tool detects anomalous log lines using LogJuicer ML-based analysis. This is specific and distinguishes it from sibling tools like get_build_log or get_build_failures, which focus on raw logs or failures rather than ML-driven anomaly detection.

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 implies usage for anomaly detection but does not explicitly state when to use this tool over alternatives or provide exclusions. It mentions a prerequisite (LOGJUICER_URL) but lacks clear guidance on selection among sibling tools.

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 readOnlyIntent and idempotent behavior, and the description goes beyond this by revealing that it parses job-output.json and returns precise failure data (task, host, error). It also distinguishes its behavior from diagnose_build, providing useful context about what it does not do (classification/log 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?

The description is concise and well-structured. It opens with a clear purpose statement, follows with the parsing behavior and sibling alternative, then lists parameters. Every sentence adds value with no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description does not need to explain return values. It covers the core purpose, the specific data source (job-output.json), and parameter semantics. The only minor gap is the lack of explicit mention of behavior when no failures are found, but given the output schema and annotations, this is adequate.

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 no parameter descriptions (0% coverage), but the description includes an Args section that explains each parameter: uuid, tenant (with default from env), and url (as an alternative to uuid+tenant). This compensates well for the schema's lack of detail, though it could be more elaborate with format or precedence rules.

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 clearly states the tool analyzes a failed build and identifies which task failed, on which host, with the error message. It also distinguishes itself from the sibling tool diagnose_build by noting it provides raw failure data, making its unique role 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?

The description explicitly recommends diagnose_build for most use cases, citing that it adds classification and log context, which gives the agent a clear alternative. However, it does not specify the exact scenarios where get_build_failures should be chosen instead, so the guidance is slightly incomplete.

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 and idempotent behavior, and the description adds substantial behavioral detail: mode semantics, grep overload behavior, context limits, max matches, noise filtering, and the direct_log_url optimization that skips metadata fetching. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a front-loaded summary followed by a concise Arg list. Each parameter line earns its place by explaining defaults, limits, or behavior. For a tool with 13 parameters, it is appropriately sized 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?

Given the tool's complexity (13 params, 0% schema coverage) and the existence of an output schema, the description covers all necessary invocation details: parameter meanings, defaults, modes, overrides, and alternate input methods. It is complete enough for an agent to select and invoke the tool 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?

The input schema has 0% description coverage, so the description fully compensates by documenting all 13 parameters with defaults, allowed ranges, mode interpretations, and interaction rules (e.g., start_line overrides mode, grep overrides mode). This is far beyond what the schema provides.

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 clearly states the tool's purpose: 'Read, search, and navigate build log files with grep, line ranges, and error summary.' It uses specific verbs and identifies the resource (build logs), while the mention of grep and error summary differentiates it from sibling tools like tail_build_log or stream_build_console.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for usage by explaining modes, parameter overrides, and the direct_log_url shortcut from prior calls. However, it doesn't explicitly state when not to use this tool or name alternative tools, so it lacks explicit when-not/alternatives 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 mark readOnlyHint, openWorldHint, idempotentHint, and non-destructive, so the bar is lower. The description adds behavioral context beyond annotations by explaining that brief returns compact metadata while brief=False returns builds, events, and timing, and that url can be used instead of uuid+tenant. It does not contradict any annotation.

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 appropriately sized and well-structured: a one-line summary, a concise note on the brief flag, and a simple Args list. Every sentence earns its place without redundancy, making it 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?

Since an output schema exists to describe return values, the description need not explain them. It adequately covers all input parameters, defaults, and the two identifier modes, providing enough information for an agent to invoke the tool correctly and understand response size trade-offs.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must fully compensate. It lists all four parameters (uuid, tenant, url, brief) with clear semantics: uuid and tenant for direct lookup, url as an alternative identifier, and brief with its effect on response detail. This adds meaning far beyond the schema's bare parameter titles.

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 'Get buildset details — result, pipeline, project, change,' which clearly specifies the action (get) and resource (buildset) and lists key contents. It distinguishes from siblings like list_buildsets by focusing on a single buildset, and from get_build by targeting the buildset level.

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 explains the brief parameter's default and how to get full details with brief=False, which is helpful for response size. However, it does not explicitly state when to use this tool over alternatives like get_build or list_buildsets; the usage context is implied by the resource name rather than 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds useful behavioral context: it discovers files via zuul-manifest.json and supports specific test formats, which goes beyond the basic annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured: it leads with the core purpose, then provides discovery context and accepted formats, and ends with a concise Args list. Every sentence adds value without fluff.

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 description covers the tool's scope (JUnit XML parsing), discovery mechanism, supported formats, and parameter semantics. An output schema exists, so explaining the return structure is handled externally. The description is complete for a read-only test-result fetch tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description fully compensates by clearly documenting each parameter: uuid, tenant, url (alternative to uuid+tenant), and failures_only (default true). This adds meaning beyond the raw schema definitions.

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 clearly states the tool's purpose: 'Parse JUnit XML test results from a build's log directory.' This uses a specific verb ('parse') and resource ('test results from a build's log directory'), and distinguishes it from sibling tools like get_build_log or get_build_failures.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool: it discovers test files via zuul-manifest.json and supports tempest, tobiko, and any JUnit XML output. It does not explicitly name alternatives or exclusions, but the context is sufficient to infer this is for fetching test results from 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint: false. The description adds valuable behavioral context beyond these: it returns ALL results (no result filtering), and the 'detail' parameter controls whether an individual build list is included. This goes beyond what annotations provide, though it doesn't discuss pagination behavior or performance implications.

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 concise and well-structured: a one-sentence purpose, a clear note about result filtering with sibling alternative, then a compact Args list. Every sentence adds value, and the formatting makes key details 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?

Given the tool's moderate complexity (8 optional parameters) and strong annotations, the description fully covers usage context: what it does, when to use it, key behavioral traits (all results, filters, pagination), and parameter meanings. Output schema is present, so return-value details are not needed in the description.

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 0%, and the description compensates by listing all 8 parameters with helpful semantics: tenant default comes from env, limit is 'Max results, 1-100 (default 20)', detail includes 'individual build list'. This adds meaning beyond the bare schema titles and defaults, though some parameters (branch, project, pipeline) are only described as 'filter' without deep detail.

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?

Description clearly states the tool computes build duration trends (avg/min/max) to detect performance regressions, using a specific verb and resource. It further distinguishes itself from the sibling get_job_durations by noting it returns ALL results with no filtering, making its purpose unique.

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?

Explicitly states when to use this tool (detect performance regressions) and provides a direct alternative: 'For SUCCESS-only averages, use get_job_durations instead.' Also clarifies that it returns all results (no result filtering), guiding the agent away from inappropriate use.

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 indicate read-only, idempotent, non-destructive behavior. The description adds real value by disclosing that it automatically fetches the latest completed buildset when not in the pipeline, shows live status with jobs/elapsed time/buildset UUID, and can reduce output size with `brief`. No contradiction with the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact, front-loaded with the core purpose, and then uses a scannable Args block. Every sentence contributes meaningful information: state-dependent behavior, parameter meaning, defaults, alternatives, and recommended polling mode. There is no fluff or repetition.

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 rich annotations, 4 simple parameters, and presence of an output schema, the description covers the main invocation modes well. The only slight gap is that it never explicitly tells the agent that one of `change` or `url` must be supplied, while the schema marks all parameters as optional.

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?

Although the input schema has 0% parameter description coverage, the Args section fully documents all four parameters: accepted formats for `change`, default behavior for `tenant`, `url` as an alternative to change+tenant, and the purpose of `brief`. This completely compensates for the empty schema descriptions.

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 clearly states "Pipeline status for a specific change or PR/MR," which is an unambiguous verb+resource+scope definition. It also distinguishes itself from generic status tools by explaining live status vs. auto-fetching the latest completed buildset, and it is appropriately distinct from sibling get_status/list_build tools.

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 useful guidance: it explains what happens when the change is in the pipeline vs. not, and it recommends the `brief` mode for repeated polls. However, it does not explicitly name alternatives or state when this tool should not be used, so it falls slightly short of full usage 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=true and destructiveHint=false, covering the safety profile. The description adds the specific component categories, which is useful but does not disclose additional operational behavior beyond what annotations and the output schema would convey.

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 that wastes no words. It conveys the action, target resource, and scope efficiently.

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 parameters and an output schema available, the description provides sufficient context by naming the component types. It is complete for the tool's simplicity and does not need to explain return values in prose.

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 has zero parameters, so the schema provides no parameter details. Per the baseline for parameterless tools, the description is not expected to document parameters, and it appropriately focuses on the resource being retrieved.

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 clear verb ('Show') and identifies the specific resource ('Zuul system components'), with concrete examples (schedulers, executors, mergers, web servers). This distinguishes it from sibling tools that focus on build, job, or node details.

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 implies when to use the tool—when you need an overview of Zuul's core components—but provides no explicit guidance on when NOT to use it or alternatives to prefer. This is adequate for a simple, parameterless tool.

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, and non-destructive behavior. The description adds useful context beyond annotations: it specifies the types of errors (broken configs, missing refs, syntax errors) and notes that tenant defaults from the environment. This provides meaningful behavioral insight without contradicting the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise and well-structured: a one-line purpose, a one-line usage hint, and a clean parameter list. Every sentence adds value, and the most important information (purpose and when to use) is front-loaded.

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 this is a simple read-only tool with two optional parameters and an output schema, the description covers the essential aspects: what it does, when to use it, and parameter meanings. The output schema handles return values, so no further detail is needed. It is complete for the tool's complexity.

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 schema has zero descriptions for its two parameters. The description compensates fully by explaining 'tenant: Tenant (default from env)' and 'project: Project filter (optional),' adding meaning beyond the raw schema. It clarifies the source of the default and the optional nature of the filter.

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 clearly states the tool's function: 'Get Zuul configuration errors — broken configs, missing refs, syntax errors.' It uses a specific verb and resource, and the examples distinguish it from sibling tools. The phrase 'First tool to check when a job isn't being triggered' further clarifies its specific role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear usage context: 'First tool to check when a job isn't being triggered.' This tells the agent when to use it, but it does not explicitly mention alternatives or when not to use it. The context is strong enough to guide selection among siblings like diagnose_build or get_build_failures.

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 no destructiveness. The description adds context about what is listed (connection type, hostname, base URL) and that it shows Zuul's code review systems, which is useful beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first states purpose, second provides details. No unnecessary words. Front-loaded with key 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?

Given no parameters, comprehensive annotations, and an output schema (exists but not shown), the description fully explains the tool's behavior and output. For a list tool, it is complete.

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?

No parameters, so schema coverage is 100%. The description does not need to add parameter info. Baseline for zero parameters is 4.

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 clearly states the verb 'List' and the resource 'configured source connections', with specific examples (Gerrit, GitHub, GitLab). The tool is distinct from sibling tools which deal with builds, jobs, etc.

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 explicit guidance on when to use this tool versus alternatives. The description implies it's for viewing connections, but does not provide conditions or 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 idempotentHint=true, so the safety profile is covered. The description adds behavioral context by explaining that the result is fully resolved after inheritance and warns that include_vars 'can be large', which is a useful operational caution beyond the schema. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is tight and well-organized: three meaningful sentences in the intro followed by a structured Args block. Every line adds value, with no redundant or vague text. It is appropriately sized for the tool's complexity.

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 exists and annotations cover safety and idempotency, the description fully explains what the tool does and its key parameters. The include_vars warning addresses a meaningful edge case. Together with the structured Args, the tool is adequately specified for correct selection and 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 0%, so the description carries full responsibility for parameter meaning. It does this excellently: pipeline includes examples ('check', 'gate'), branch has a default, tenant default is from env, and include_vars is explained with a size warning. This compensates fully for the missing schema descriptions.

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 clear verb-object pair ('Get fully-resolved job configuration') and adds specificity with 'after inheritance'. It further explains the output ('final merged nodeset, timeout, and playbooks'), which distinguishes it from sibling tools like get_job and get_freeze_jobs. The phrase 'Use to understand exactly what a job will do' reinforces the tool's purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear when-to-use guidance: 'Use to understand exactly what a job will do.' It implies this tool is for seeing the fully merged configuration, but it does not explicitly name alternatives or state when not to use it. The 'after inheritance' context hints at the distinction but lacks an explicit exclusion.

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, and non-destructive behavior. The description adds context about inheritance resolution and dependency display, giving insight into the computational behavior. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The main description is concise and front-loaded with the core purpose. The Args block adds necessary parameter context, but partially duplicates schema information, making it slightly longer than strictly necessary.

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 adequately explains the tool's function, usage, and parameters. It doesn't discuss error cases or edge scenarios, but that is not critical given the available schema.

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 0% description coverage, but the description includes an Args section explaining each parameter with examples (e.g., pipeline examples, branch default, tenant default). This fully compensates for the schema's lack of descriptions.

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 clearly states that the tool gets the resolved job graph for a pipeline/project/branch, showing which jobs will run with inheritance and dependencies resolved. This specific verb+resource pairing distinguishes it from sibling tools like get_freeze_job (singular) and get_job.

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 a clear use case with 'Use to understand job ordering,' which implies when to apply the tool. However, it does not explicitly compare against alternatives or state when not to use it, so it falls short of 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, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds the list of returned configuration fields but no additional behavioral traits (e.g., authentication, error cases). No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: one front-loaded sentence for purpose and a compact two-item Args list. No filler or redundant 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?

For a simple read-only configuration retrieval with comprehensive annotations and an output schema, the description adequately covers the tool's scope. Minor vagueness in 'all variants' does not detract significantly.

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 no parameter descriptions (0% coverage). The description's Args section clarifies 'name' as 'Job name' and 'tenant' as 'Tenant (default from env)', adding meaningful semantics beyond the raw 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 uses the specific verb 'Get' and identifies the resource as 'job configuration' with concrete fields (parent, nodeset, timeout, branches). This clearly distinguishes it from sibling tools like list_jobs (list) and get_build (build-specific resource).

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 implies usage when one needs job configuration details but does not explicitly state when to use this tool versus alternatives like list_jobs or get_build. No exclusions or preferred contexts are mentioned.

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 the readOnly/idempotent annotations, the description discloses concrete behavioral traits: parallel fetching of build history, a default result filter of 'SUCCESS' for clean averages, and a limit cap of 50. These details help the agent understand side effects and defaults beyond 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?

The description is tightly structured: a one-sentence summary, a behavior note, a use-case sentence, and a minimal Args list. No fluff; every sentence adds value. The key information is front-loaded.

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 tool has an output schema, the description need not explain return values. It covers purpose, behavior, use context, and all parameters comprehensively. Annotations handle safety traits. The description is fully sufficient for an agent to select and invoke the tool 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?

With 0% schema description coverage, the description carries full burden and succeeds by explicitly listing each parameter with meaning: job_names, tenant (default from env), result (default 'SUCCESS'), and limit (default 10, max 50). It adds context not visible in the schema, such as the rationale for the default result filter.

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 avg/min/max duration for multiple jobs in a single call.' It clearly states the batch scope, distinguishing it from single-job tools like get_job or get_build_times. The added detail about parallel fetching reinforces its unique function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: 'Designed for monitoring tools that need durations for an entire pipeline chain.' This implies when to use it, but it does not explicitly name alternatives or state when not to use it. It conveys the batch vs. single-call distinction implicitly.

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 indicate a safe, idempotent read operation. The description adds context that 'configuration' refers to pipelines and jobs, but does not disclose additional behaviors such as error handling or requirements. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded with the primary purpose, followed by a brief parameter list. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with a clear read-only purpose, strong annotations, and an output schema. The description covers the essential purpose and parameter hints, though it could differentiate from similarly named sibling 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?

Schema coverage is 0%, so the description must compensate. It lists both parameters and enriches the name parameter with an example and clarifies the tenant default as 'from env', though it could provide more detail on parameter semantics.

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 clearly states the tool retrieves project configuration, specifying that it covers configured pipelines and jobs. This distinguishes it from sibling tools like get_job or list_projects by focusing on the project-level configuration.

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 does not explicitly provide when-to-use guidance or alternatives. It implies usage via the purpose statement but lacks exclusions or comparisons to sibling tools, leaving the agent to infer appropriate usage.

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?

While annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, the description actually ADDS confusion rather than clarity. The mention of 'showing what's currently queued/running' in the description could be read as too narrow (suggesting only active items are shown) when active_only defaults to true but is configurable. No disclosure of rate limits, scope limitations, or details about 'live' semantics (is this a snapshot managed internally? What are the consistency guarantees during concurrent writes?). The description should clarify that this endpoint only reads and never mutates state, which is especially important when a sibling tool like autohold_create could be a follow-up action.

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?

Four short, active sentences. The 'live' framing and the explicit note about pollability are immediately useful. The mention of 'roughly 50%% smaller' is a useful approximation for agents considering retention versus bandwidth. Each sentence earns its place — no filler or redundant phrasing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a 5-parameter tool defaulting active_only=true and zero schema coverage, the description must clarify query semantics, default behavior, and interaction between parameters, but doesn't explain why a user would set active_only=false. There's no mention of what the output contains (which the output schema presumably documents) but also no mention of time-window limitations, whether 'brief' affects the output schema differently, or whether pagination exists for large pipelines. The description covers the tool's nice-to-haves but leaves core behavioral gaps unfilled.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden, but it doesn't do much beyond restating parameter names. The description says 'tenant' is 'default from env' and 'brief' 'reduces output' which mirrors the schema's own documentation, adding only marginal context about 'brief' reducing size by ~50% and tenant's env fallback. The main contribution is the '(default from env)' clarification for tenant — that's genuinely useful — but the context for pipeline and project is minimal, and there's no mention of query semantics for pipeline or project.

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 'Live pipeline status showing what's currently queued/running' uses a specific verb (get/show status) with a clear resource scope (pipelines) and states a behavioral trait (the 'live' aspect indicating real-time visibility into queued/running items). It's clear enough to distinguish from most siblings (e.g., get_build, list_jobs), though it doesn't explicitly name alternatives like list_pipelines. The Live/queued framing differentiates it from static resource-listing siblings like list_buildsets or get_config_errors.

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 implies polling usage via the 'brief' parameter ('for repeated polling') and is named 'Live pipeline status' with a default state of active_only=true, which implies it's for monitoring. However, there's no explicit when-to-use/when-not-to-use guidance, and with 43 siblings available (list_builds, get_build, diagnose_build, etc.), the description misses the opportunity to clarify when get_status is more appropriate than querying individual build status endpoints.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds minimal behavioral context beyond the annotation profile, only listing the data fetched (capabilities, auth config, websocket URL). It does not add details about permissions or response behavior, but the annotation coverage is sufficient for a read-only call.

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 extremely concise: a single sentence with the purpose plus an Args line for the parameter. It is front-loaded, contains no filler or redundancy, and every part adds value.

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 is simple (one optional parameter, no nesting), annotations cover safety (read-only, idempotent), and an output schema exists so return format is structurally documented. The description fully captures what the tool does and its parameter, making it complete for this complexity level.

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?

Although schema description coverage is 0%, the description includes an 'Args' section that explains 'tenant' as a tenant string with default from env. This adds meaning beyond the raw schema and compensates for the lack of schema descriptions, making the parameter's role clear.

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?

Description states 'Get tenant capabilities, auth config, and websocket URL.' This clearly identifies the verb (get), resource (tenant), and specific data returned. It is distinguishable from list_tenants and other get_* tools by focusing on a single tenant's detailed info, but it does not explicitly compare to 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?

Usage is implied: the tool gets tenant-specific information, with a tenant parameter defaulting from env. No explicit when/when-not guidance or alternatives are mentioned. The absence of any stated context or exclusions brings it to an implied-usage level rather than explicit 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=true and idempotentHint=true, and the description adds context about combining multiple operations into one response, which is useful. It does not disclose any side effects beyond that, but given the annotations, the bar is met. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is fairly concise, but the use of a multi-line Args block with plain text is somewhat verbose. The core description is front-loaded with a clear one-liner, and the extra detail on parameters is structured. It earns the score for efficiency without waste, though formatting could be improved with bullet points.

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 a moderate complexity (combining multiple operations) and an output schema exists, so return values are covered. The description explains the combining behavior and parameter filtering. However, it does not mention edge cases like what happens for invalid change numbers or how autohold filtering works in detail, but given the output schema and annotations, completeness is adequate.

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 provides brief parameter explanations: 'change' as the change number, 'job' as a substring filter, and 'tenant' defaulting from env. However, schema description coverage is 0%, and the description only adds a bit of detail beyond the schema (e.g., substring matching and filtering behavior). It could provide more detail on parameter formats or defaults.

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 clearly states it is a one-call investigation tool that combines building, diagnosis, and autohold status into a single response. It explicitly names the combined functions (list_builds, diagnose_build(brief), autohold lookup) and distinguishes it from alternatives.

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 that the tool is designed for the common 'what's happening with this change?' workflow and replaces 3-4 separate tool calls, giving clear context on when to use it. However, it does not explicitly state when not to use it or list direct alternatives within the description, though sibling tools imply alternatives.

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, destructiveHint=false. The description adds valuable behavior beyond annotations: project filter uses a project-scoped API endpoint for server-side filtering, job filter is client-side, and tenant defaults from env. No contradictions.

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 a clear purpose and use case, followed by a structured Args list. Every sentence earns its place; no redundant or extraneous 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?

For a simple read-only list tool with an output schema, the description covers purpose, parameters, and key behavioral differences (server vs client filtering). The optional parameters and output schema are already structured, so no further explanation is needed.

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 has 0% description coverage, but the description's Args section fully compensates by explaining each parameter: tenant (default from env), project (server-side substring match via project-scoped endpoint), job (client-side substring match). This is exactly what the schema lacks.

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+resource ('List autohold requests') and explains what autoholds are ('nodes held after failure for debugging'), distinguishing it from sibling tools like get_autohold (single item) and autohold_create/delete (mutations).

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?

Provides clear usage context: 'Check when jobs are stuck waiting for nodes or to find your autohold.' It does not explicitly name alternative tools, but the purpose and parameters imply when listing is appropriate versus other operations.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds that results are 'compact build summaries,' which is useful, but doesn't disclose other behaviors like pagination details or result ordering. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is optimally structured: a one-line summary followed by a clean argument list. Every line is informative, no fluff. The front-loaded summary immediately conveys the tool's purpose.

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 search tool with an output schema, this is quite complete. It covers all filters, return type, and even default behavior for tenant. It lacks explicit guidance on when to use vs siblings, which would make it fully complete, but the core information is present.

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 0%, so the description must carry parameter meaning, and it does: it explains each filter's purpose, gives examples for result (SUCCESS, FAILURE, etc.), specifies ISO 8601 format for time bounds, and provides a 1-100 range for limit. Some entries like 'Project filter' are thin, but overall it adds significant value over the schema's bare names.

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 clearly states 'Search builds with filters' and 'Returns compact build summaries,' giving a specific verb and resource. It distinguishes from get_build by implying search/list behavior, though it doesn't explicitly name alternatives.

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 makes it obvious that this tool is for searching/filtering builds, but it doesn't provide explicit when-to-use vs alternatives, nor mention any exclusions. Usage context is implied by the filter parameters rather than 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 establish this as read-only, idempotent, non-destructive, and open-world. The description adds valuable behavioral context beyond annotations, notably the performance trade-off for 'include_builds: Fetch full details per buildset (slower, best with limit <= 5)', which is critical for effective use. No contradictions found.

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 well-structured: a clear one-sentence purpose followed by an 'Args' block with one-line explanations for each parameter. It is appropriately sized for 14 parameters, with no redundant or filler content. Every line earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 14 parameters and no schema-level descriptions, the description covers all parameters meaningfully. It also explains the buildsets concept and includes a performance caveat for include_builds. Given the output schema exists, return values are not needed. The description is complete for this tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden for parameter meaning. It does so excellently: every parameter (tenant, project, pipeline, change, branch, ref, result, time filters, limit, skip, include_builds) gets a concise explanation. It also includes constraints and defaults, such as 'limit: Max results, 1-100 (default 20)', which are not in 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 opens with 'Search buildsets' and immediately defines buildsets as 'groups of builds triggered by a single event', which clearly states the tool's function and distinguishes it from sibling tools like list_builds or get_buildset. The verb 'Search' and resource 'buildsets' are specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool by explaining it searches buildsets with various filters, and it defines what a buildset is. However, it does not explicitly mention alternatives or when not to use it, leaving some inference to the agent.

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, and open-world behavior. The description adds that the output includes build status and upload artifacts, which gives useful context about the data scope beyond the schema. No behavioral claims contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences plus a one-line Args section, front-loaded with the purpose. No filler or repetition; every sentence 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?

Given a simple list operation, an output schema to define return data, and strong annotations, the description covers the essential use case and the single parameter's default source. The tool's behavior is fully specified for an agent to invoke 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 0%, so the description must compensate. It explains the 'tenant' parameter as a tenant name and states that it defaults from the environment, adding meaning beyond the schema's bare string type and empty default. This is sufficient for a single optional parameter.

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-resource pair ('List nodepool disk images') and adds scope ('with build status and upload artifacts'). It is clearly distinct from sibling tools like list_nodes or list_pipelines, so purpose 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?

The description implies usage by stating the tool lists images, but it provides no explicit guidance on when to choose it over alternatives or any exclusions. For a straightforward list tool, this is adequate but not exemplary; no comparison to sibling tools is offered.

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 description adds behavioral detail beyond the readOnly/idempotent annotations: it explains filter case-insensitivity, the limit default and behavior of 0 for unlimited, and the tenant default from environment. This provides useful context that the annotations alone do not cover.

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 extremely concise, with a clear first sentence followed by a bullet-like args list. Every sentence is necessary and adds value, with no redundant or filler 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?

The description covers essential functionality and parameter details, and the presence of an output schema handles return value documentation. Minor gaps like ordering or pagination are not disclosed, but for a simple list endpoint with good annotations, the completeness is 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 input schema has no descriptions, so the description fully compensates by defining each parameter: tenant default from env, case-insensitive name substring filter, and limit with default 200 and 0 for unlimited. This removes ambiguity that would otherwise exist.

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 clearly states 'List all jobs in a tenant' with an optional substring filter, using a specific verb and resource scope. It distinguishes itself from siblings like get_job by explicitly covering the plural 'all jobs' and the tenant scope.

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 implies usage context ('in a tenant') but does not explicitly state when to prefer this over alternative tools like get_job or list_pipelines. There is no direct mention of exclusions or alternative guidance, leaving the agent to infer the appropriate scenario.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds no additional behavioral context such as pagination, result limits, or side effects. It merely restates the listing operation, so transparency is not enhanced beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences, front-loading the purpose first and then documenting the sole parameter. No wasted words. It is appropriately sized for a simple list tool.

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 is a simple read-only listing operation with one optional parameter and an output schema, so the combination of annotations, output schema, and this description largely covers the necessary context. However, it lacks explicit guidance on when to choose this tool over the many sibling list tools, which is a minor gap.

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 schema has one parameter 'tenant' with only a title and empty default, giving 0% description coverage. The description compensates by stating 'tenant: Tenant (default from env),' which clarifies that the default is read from the environment rather than being a literal empty string. This adds meaningful information beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List available nodepool labels' and clarifies they are 'node types that jobs can request.' This uses a specific verb and resource, and distinguishes from sibling list tools like list_nodes and list_projects.

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 does not explicitly state when to use this tool versus alternatives. The phrase 'node types that jobs can request' implies the use case of checking available node types for jobs, but no alternatives are named or exclusions given. This is implied usage rather than explicit 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=true and destructiveHint=false. The description adds meaningful behavior: the default summary output vs detail=true for individual nodes, and the limit parameter with 0 for unlimited. This goes beyond safety to explain output behavior, which is valuable.

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 sections: purpose, use case, and args. It front-loads the primary purpose and uses a clean list format for parameters. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return value details are covered. The description covers all parameters, default behavior, and the diagnostic use case. It's complete for a read-only list tool with no nested structures.

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 has 0% description coverage, so the description fully compensates by explaining each parameter: tenant (default from env), detail (include individual node list), and limit (max nodes, 0 unlimited). This adds meaning beyond the raw 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 opens with 'List nodepool nodes — available, in-use, or provisioning,' which clearly states the action and resource, and enumerates the node states. This distinguishes it from other list tools like list_jobs and list_projects by focusing specifically on nodepool nodes.

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 provides an explicit use case: 'Check when jobs are stuck waiting for nodes.' It also gives guidance on parameter selection ('Summary by default, set detail=true for individual nodes'). However, it doesn't explicitly mention alternatives or when not to use, so it's 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, idempotentHint, openWorldHint, and destructiveHint=false, covering the safety profile. The description adds that the result includes trigger types, but does not disclose behavior like pagination or performance implications.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences plus a minimal Args block, front-loading the main purpose with no fluff.

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 one optional parameter, an existing output schema, and robust annotations, the description is largely sufficient. It clearly states the scope ('all pipelines') and the included information (trigger types), and nothing essential seems 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 0% (no parameter descriptions in the schema), so the description must compensate. It provides a brief but meaningful note that 'tenant' defaults from environment, which adds context beyond the schema's default empty string.

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 clearly states the tool lists all pipelines and includes their trigger types, using the verb 'list' and specifying the resource. It distinguishes from sibling list tools which target different resources (e.g., list_projects, list_nodes).

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 no explicit guidance on when to use this tool versus alternatives, nor any exclusions. However, the straightforward nature of a 'list all' operation makes the usage context clear, and there is no obvious sibling alternative for listing pipelines.

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. The description adds useful parameter-level behavior (case-insensitive filter, tenant from env, limit semantics) but does not disclose additional operational traits like pagination or rate limits. It does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose in the first sentence, followed by a compact Args block. Every sentence adds value, with no fluff or repetition of schema defaults.

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 tool's simplicity, rich annotations, and presence of an output schema, the description covers purpose, filtering, defaults, and limits. It is sufficiently complete for an AI agent to select and invoke 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 0%, so the description carries the full burden. It explains all three parameters with semantics beyond the schema: tenant defaults from env, filter is case-insensitive substring, limit has special 0=unlimited behavior. This fully compensates for the missing schema descriptions.

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 clearly states 'List all projects in a tenant' with a specific verb and resource, and optionally filter by name. It distinguishes from siblings (like get_project or list_pipelines) by the resource type, though it does not explicitly name an alternative.

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 implies when to use the tool (when listing projects) but does not explicitly state when not to use it or mention alternatives. The optional filter and default tenant provide some context, but there is no direct comparison to sibling tools like get_project.

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, destructiveHint, idempotentHint, and openWorldHint, covering the safety profile. The description adds that the tool returns flavors and images, but does not disclose additional behavioral traits such as ordering, pagination, or how tenant affects results. This is consistent with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence plus a concise argument line. It contains no filler or redundant phrases, and the structure clearly separates the main action from the parameter documentation.

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 strong annotations, the description is nearly adequate for a simple one-parameter listing tool. It lacks a bit of context about the 'nodepool' concept or how tenant scoping works, but overall it provides sufficient coverage for the tool's simplicity.

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 adds the note 'default from env' for the tenant parameter, which goes beyond the schema's simple default of empty string. However, it does not explain what tenant means in the context of providers or how it filters results, leaving the parameter only partially explained.

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 'list' and a clear resource 'nodepool cloud providers', and specifies the content ('flavors and images'). This clearly distinguishes it from sibling list tools like list_projects, list_nodes, and list_images.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or relationship to sibling tools. The argument line is about the tenant parameter, not usage context.

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, covering the safety profile. The description adds meaningful context by explaining what semaphores are, which goes beyond the annotations. It doesn't mention auth or rate limits, but the annotation coverage lowers the bar, and the conceptual definition adds value.

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 extremely concise: two sentences and an args list. It front-loads the core purpose ('List semaphores') and follows with a practical use case. Every sentence contributes without redundancy or 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?

Given the tool's simplicity (one optional parameter) and the presence of an output schema, the description is largely complete. It states what semaphores are, when to use the tool, and the one parameter's default. It omits potential filtering/scope details, but for a list tool with annotations covering safety, this is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It documents the tenant parameter with '(default from env)', adding an environment-default nuance not present in the schema. However, it does not elaborate on what tenant means or how it affects results, leaving partial ambiguity for the single parameter.

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 ('List') and resource ('semaphores'), then defines semaphores as 'resource locks that limit concurrent job execution.' This clearly distinguishes it from sibling tools, and the added use case 'Check when jobs are waiting unexpectedly' reinforces its diagnostic purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear usage context: 'Check when jobs are waiting unexpectedly.' This implies when the tool should be used (diagnosing unexpected waits). However, it does not explicitly name alternative tools or state when not to use it, so it stops short of full guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds minimal behavioral context beyond the listed examples, such as pagination via skip and limit defaults, but does not disclose ordering, event type value formats, or any special behavior. It does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is exceptionally concise: one purpose sentence followed by a clean argument list. Every sentence earns its place, with no redundant filler or repetition of schema defaults.

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 presence of an output schema and strong safety annotations, the description covers the essential purpose and all parameter semantics. It lacks some behavioral details like result ordering or event_type accepted values, but for a simple list operation the provided context is nearly complete.

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 0% schema description coverage, the description fully compensates by explaining every parameter: tenant (default from env), event_type (filter), limit (max results, default 50), and skip (pagination offset). This adds concrete meaning that the bare schema properties lack.

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 'List system events' and immediately specifies the scope with examples ('config updates, reconfigurations, pipeline changes'). This provides a specific verb, resource, and meaningful content that distinguishes it from sibling list tools like list_builds or list_jobs.

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 guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or point to sibling tools. The description implies usage for listing system events, but lacks contextual direction or comparisons.

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, and non-destructive behavior. The description adds value by specifying the data returned (project and queue counts), which is beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no redundant information, front-loaded with key action and resource.

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 tool's simplicity (no parameters), the description fully covers what the tool does and what it returns, and an output schema likely exists for further detail.

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?

There are zero parameters, so the description does not need to add parameter details. Baseline for 0 params is 4.

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 clearly states the action (list) and resource (Zuul tenants) and specifies the output includes project and queue counts, making it distinct from sibling tools.

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 does not explicitly mention when to use this tool versus alternatives, but its purpose is clear and the context of listing all tenants is unambiguous.

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 description adds valuable behavioral context beyond the annotations: it uses WebSocket, only works for running builds, requires the 'console' extra package, and has configurable lines/timeout limits. Annotations already declare readOnlyHint and idempotentHint, so the added operational constraints are a plus, though error/stream-end behavior is not described.

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 well-structured and front-loaded: the first sentence gives the core purpose, followed by clear usage constraints and a compact Args list. Every sentence adds necessary information without fluff.

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?