UI Verify

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

The description discloses important side effects beyond the annotations: it advances each story's per-branch baseline, accepts stories with prior denied reviews, leaves failed stories unaffected, and returns the post-acceptance triage. This gives the agent a clear model of what changes and what does not.

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: main action first, then usage condition, then behavioral side effects, then return behavior. Every sentence adds useful information and there is no filler.

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

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

For a mutation tool with annotations and an output schema, the description covers the key behavioral context: what gets accepted, which stories are affected, what happens to baselines, and what the response contains. No essential operational detail is missing.

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

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

Schema coverage is 100%, so the schema already explains each parameter. The description only restates the identifiers ('commitSha/prNumber/buildId') without adding new meaning such as precedence, mutual exclusivity, or default behavior when multiple are supplied.

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

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

The description states a specific verb and resource: 'Accept ALL changed stories in one build at once.' It also distinguishes itself from the sibling tool review_diff by explicitly calling itself 'the bulk form of review_diff=accept,' so an agent can correctly separate it from per-story review 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?

It gives an explicit usage condition: 'use it when you've decided the whole build's changes are intended.' It also names the relevant alternative (review_diff) and implies per-story review for non-bulk decisions, giving clear routing guidance.

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

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

Beyond the readOnlyHint annotation, the description discloses significant behavior: only the first 25 items are returned, cursors indicate pagination, changed stories are ordered likely-regressions-first, unchanged stories are deliberately omitted, failed stories distinguish render vs interaction errors, and error truncation is indicated. This is rich, accurate behavioral 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 front-loaded with the core purpose and resolver rule, and every clause contributes meaningful guidance. It is long because it covers many response details and routing decisions, but some of the return-field enumeration overlaps with the existing output schema. Still, no content is wasted.

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

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

For a complex triage tool, the description covers resolution rules, response contents, pagination, ordering, error kinds, and explicit redirection to the correct sibling tools. Given the rich output schema and annotations, nothing essential is missing for an agent to select and invoke 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?

The schema already documents each parameter with 100% coverage, so the baseline is solid. The description adds the crucial constraint that exactly one resolver must be provided, which the schema does not enforce. It does not need to repeat individual parameter descriptions because the schema already handles them.

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 starts with a specific action ('Triage one build') and identifies the exact resource and resolvers (commitSha, prNumber, buildId). It clearly distinguishes this from the sibling pagination/listing tool by stating what this call does NOT return and pointing to list_build_stories, get_diff, and render_diff_image.

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 explicit when-to-use and when-not-to-use guidance: use it for triaging one build and reviewing changed/failed stories; use list_build_stories for unchanged stories or pagination; use get_diff or render_diff_image for images. This makes tool selection 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?

Annotations already declare readOnlyHint=true, and the description matches that by describing a read-only detail query. It adds valuable behavioral context beyond annotations: URLs are presigned and time-limited, unchanged stories return a special shape with diffResultId null and changed false, and AI review fields are null when review did not run. No contradiction with annotations exists.

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 dense and front-loaded, starting with the core purpose and resolution paths. It packs necessary usage, edge-case, alternative-tool, and AI-field behavior into a few sentences. The AI field enumeration is slightly long, though useful, which keeps it from a perfect score.

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

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

For a read-only tool with an output schema and four optional-looking parameters, the description is largely complete: it covers resolution paths, defaults, the main edge case, URL behavior, and the close sibling alternative. A minor gap is that it does not state what happens if no build identifier is supplied, even though the schema lists 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?

The schema already covers 100% of parameters with brief descriptions, so the baseline is 3. The description adds meaning beyond that by explaining the default behavior of storyId (default to changed stories) and the unusual unchanged-story result semantics. It does not add much per-parameter syntax, but the added scope and edge-case semantics justify one point above baseline.

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

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

The description states a specific verb and resource ('Per-story diff detail for a build') and immediately clarifies the resolution paths (commitSha/prNumber/buildId). It also distinguishes itself from a close sibling by saying 'Use render_diff_image instead when you want the actual pixels inline for a vision model, not a URL.' This lets an agent separate get_diff from render_diff_image without opening schemas.

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

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

The description gives explicit when-to-use guidance: get_diff is for diff metrics and URLs, and render_diff_image is the alternative when inline pixel data is needed. It also explains the default story scope, the optional storyId override, and the unchanged-story edge case, which is exactly the kind of usage context an agent 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 only say readOnlyHint=true; the description goes well beyond that by explaining the resolved-by semantics (commitSha/prNumber/buildId), the independent-of-review-state behavior, and especially the `removed` list which surfaces otherwise-invisible baseline deletions with lastBuildId context. It also notes the feature requirement and the absence of image URLs, both useful behavioral disclosures.

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 long but information-dense: every clause earns its place, and the most decision-relevant contrast (vs get_build, survives in-PR accepts) is front-loaded. It trails into a multi-item return-value inventory, which makes it slightly heavy, but that inventory includes behavioral caveats (removed stories carry lastBuildId) rather than mere schema 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?

The description covers what the tool answers, how it differs from its closest sibling, what the response contains including pagination cursors, and how to get pixels elsewhere. With an output schema present, return-value detail is appropriately summarized. For a read-only changeset query, this is complete at the right level of 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that resolution can come from any of the three identifiers and that the result is 'resolved by commitSha/prNumber/buildId', tying the parameters to the same concept. It doesn't explain precedence among them, but the schema already documents each field adequately.

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 precise noun phrase and verb — 'cumulative this PR vs base visual changeset' — and immediately distinguishes it from get_build by the in-PR accept behavior. It names siblings and states exactly what it returns (base, counts, first page of stories, deleted stories with lastBuildId).

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 contrasts with get_build ('unlike get_build...') and even explains the carve-out for mid-PR accepted stories, so an agent knows when to choose this tool over the alternative. It also tells the caller to page with list_pr_stories and fetch pixels with get_diff / render_diff_image, which are concrete routing instructions.

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 the tool as read-only, and the description adds useful behavioral context: results are newest-first rows containing only a gateStatus verdict, and the tool intentionally omits image URLs and per-story details. This goes 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?

Three sentences, all information-dense and front-loaded with the core purpose before limitations and alternatives. Every sentence earns its place, and there is no redundant restating of the schema or title.

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

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

For a read-only list tool with an output schema present, the description covers what an agent needs: what the rows look like, how results are ordered, what is intentionally excluded, and which sibling tools to use for the excluded details. No critical call-time context is missing.

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

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

The input schema fully documents all three parameters (limit, branch, status) with descriptions and enumerations, so the schema carries the parameter-meaning burden. The description does not add additional parameter semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb and resource ('List recent UI Verify builds'), specifies ordering ('newest first'), and defines the output scope ('one-line verdict'). It also differentiates itself from siblings by explicitly stating what it lacks ('no image URLs or per-story detail') and naming the alternatives for those 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 gives explicit usage direction: use this to find the build to inspect, then 'call get_build for the changed-story list, get_diff for images.' This directly routes the agent to the correct sibling tools and states the boundary of this tool's usefulness.

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 discloses behavior far beyond the annotations: what each status returns, ordering for changed stories, cursor semantics with nextCursor, default/max limit, and the edge case that unchanged stories are only available after the build settles. This is rich, non-obvious behavior.

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

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

The description is dense but every clause earns its place. It front-loads the purpose, then covers status behaviors, return shape, paging, limits, and a timing edge case without redundant 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?

The description is complete for a paginated read-only tool: it explains return shape, pagination, status-specific semantics, build resolution, and the important unsettled-build behavior. No significant gap remains for an agent to call it correctly.

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

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

Although schema coverage is 100%, the description adds substantial meaning: it explains the exact meaning of each status value, how cursor should be passed back, how build resolution works via commitSha/prNumber/buildId, and the limit default. This goes well beyond the bare 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 states a specific verb and resource: page through one build's stories filtered by status. It also distinguishes itself from get_build by noting it reads past get_build's first page and includes unchanged/passed stories that get_build only counts.

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 says when to use it: to read past get_build's first page or to browse unchanged/passed stories. It also gives follow-up guidance for retrieving images with get_diff or render_diff_image, helping the agent choose the correct tool chain.

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 readOnlyHint=true and openWorldHint=false, and the description adds meaningful behavior: exact semantics of new/changed/removed, that removed stories carry lastBuildId rather than review status/verdict, the cursor round-trip contract, and the default/max limit. No statement contradicts 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 information-dense but every clause earns its place: pagination role, kind semantics, output shape, cursor handling, limit, and feature gate. It is front-loaded with the core action and routing hint before the detailed kind definitions.

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

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

For a 6-parameter paging tool, the description plus the provided schema and output schema cover resolution modes, pagination state, return shape, defaults, and prerequisites. An agent has what it needs to call the tool correctly and continue paging.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond the schema by defining what each kind means (e.g., 'even if accepted mid-PR, with status=accepted') and how cursor pagination works. It does not fully remove ambiguity about whether exactly one of commitSha/prNumber/buildId must be supplied, which keeps it from a 5.

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 ('Page through'), a precise resource ('PR-vs-base changeset stories'), and a kind selector, then immediately ties it to the sibling tool: 'read past get_pr_changeset's first page'. Each kind value gets a distinct semantic definition, so an agent can tell this apart from get_pr_changeset and list_build_stories without opening schemas.

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

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

It explicitly names get_pr_changeset as the tool whose first-page result this continues, giving the when-condition ('read past ... first page'). It also states the prerequisite ('Requires the PR visual changeset feature'), which prevents calls in unsupported contexts.

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?

Even though annotations already declare readOnlyHint=true, the description adds substantial behavioral context: output is inline base64, before_after crops to changed regions and stacks multiple crops, and the tool errors when an image genuinely doesn't exist. This goes well beyond the annotations and fully discloses the tool's runtime behavior.

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

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

The description is long but every sentence earns its place; the tool genuinely has two distinct invocation modes and nuanced image-format behavior. It is front-loaded with the core purpose, then logically organized into the two addressing forms, with caveats placed in context.

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 tool with 6 optional parameters, two call forms, no output schema, and no nested objects, the description fully covers the invocation methods, image variants, error behavior, and how to get the required IDs. Nothing needed to call the tool correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description goes further by explaining the two valid parameter combinations, the meaning of each `which` value (including before_after's side-by-side crop behavior), and how to obtain diffResultId from get_build/get_diff. This transforms the flat parameter list into actionable usage knowledge.

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

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

The description states a specific verb and resource: fetch a story's image as an inline base64 image for vision-model consumption. It clearly distinguishes itself from get_diff by noting that get_diff returns URLs while this tool returns pixels, so an agent can tell them apart.

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 says when to use this tool (vision-model needs pixels), when NOT to use it (piped through raw curl, use get_diff's URLs), and gives two concrete addressing forms with step-by-step guidance. It also identifies the only way to view unchanged/passed story pixels, leaving no ambiguity about tool 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?

The description fully discloses the persistent side effects of each decision: accept changes the baseline so the next build is clean, deny records rejection without changing baseline, ignore permanently excludes the story from the gate while the snapshot keeps differing. It also notes attribution to the project key, which is useful context 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 information-dense but not bloated; it front-loads the core purpose and then expands each decision. Every sentence adds either behavioral clarity or workflow guidance, and the length is justified by the need to distinguish three decision outcomes.

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

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

For a two-parameter write operation with a fully documented schema and an output schema present, the description covers the workflow, side effects, parameter sourcing, and decision criteria. No critical operational detail is missing.

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

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

Schema coverage is 100%, so both parameters already have descriptions. The description adds value by explaining the real-world consequences of each decision value and reinforcing that diffResultId comes from get_build/get_diff, but it does not introduce semantics the schema entirely 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?

The description opens with a specific verb and resource ('Record a review on a single diff result') and then defines each decision outcome ('accept' makes the candidate the new baseline, 'deny' records rejection, 'ignore' persists gate exclusion). The title and 'single diff result' wording distinguish it from build-level siblings like accept_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?

It explicitly says when to use the tool: 'Use after you've inspected the diff (e.g. with render_diff_image) and decided intended vs. regression.' It also gives a concrete use case for 'ignore' (intentional ongoing diffs like animation or live timestamp). It does not explicitly contrast with a sibling alternative like accept_build, so no exclusions are stated.

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