Veridu

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

Beyond the readOnly and idempotent annotations, the description adds important behavior: it waits up to ~45 seconds, may return a result or stage_label, and should be called again after reporting the stage. This explains the polling and wait semantics that annotations alone do not capture.

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 short, front-loaded with the core action, and each sentence carries useful information: scope, non-behavior, wait time, return behavior, and next-step instruction.

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 one-parameter read-only polling tool with rich annotations, the description covers the important operational behavior and return alternatives. It could say more about the shape of the result object, but it is largely 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?

The only parameter is documented at 100% schema coverage, and the schema already explains that change_id comes from verify_change. The description implies the same relationship but adds no new syntax or format details beyond the schema 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: fetching the result of a verify_change that was still running. It also explicitly distinguishes itself from the likely sibling verify_change by saying it never starts a new review.

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 clearly says to use this after a verify_change is still running and instructs the agent to tell the user the stage_label and call again. It does not explicitly compare against veridu_review_status or veridu_review, so it falls short of full alternative routing.

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 annotations (which already declare non-read-only, open-world, idempotent, non-destructive), the description adds billing behavior, the dedupe mechanism ('same pull request head returns the existing review'), the fact that no credentials pass through the tool, and panel composition rules including the first-per-vendor-wins tiebreak. This is exactly the kind of context annotations cannot express.

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

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

The opening sentence front-loads purpose and the follow-up sentence explains the review pipeline before the operational Notes. The pipeline sentence is somewhat elaborate ('ungrounded findings are dropped') but it carries real behavioral information rather than filler; the structure is scannable and nothing is wasted.

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

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

With no output schema, the description still lists what comes back (outcome, agreements, disputes, per-reviewer findings). Auth, private-repo setup, cost, and idempotency are all covered, so an agent has everything needed to call this correctly on first attempt.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully extends the `models` parameter: at least two distinct vendors required, tier-gated models need a paid account, duplicates per vendor resolve to the first, and omission falls back to the account default panel. Those are behavioral constraints the schema does not encode.

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

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

The description gives a specific verb and resource ('Review a GitHub pull request with Veridu') and explains the differentiating mechanism: finding callers and implementations affected by the change, cross-reviewer gating, and dropping ungrounded findings. It implies but never names the sibling tools (veridu_review_status, verify_change), so routing is inferred rather than explicit.

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 states the situation for use (reviewing a PR with dependency context), prerequisites (Veridu account, private repos linked at veridu.io/repos), and cost implications ('counts as one review on that account'). It does not explicitly contrast with the sibling tools get_change, verify_change or veridu_review_status, leaving the agent to infer when those are preferable.

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 say readOnly and idempotent, but the description adds behavior annotations cannot express: it blocks up to ~45 seconds waiting, never counts as an attempt, and returns a stage_label the agent is told to relay to the user. The cost/consume semantics and the latency are the exact facts an agent needs before invoking.

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 key constraint (check, don't restart) is front-loaded in the first two sentences. It runs a bit long with the emphasis on DO NOT and the restated call-again instruction, but every block carries distinct operational information rather than 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?

There is no output schema, but the description describes what comes back (stage_label indicating whether reviewers are still on the change or Veridu is checking outside code) and what to do with it. Combined with the polling-loop instruction, nothing needed to call this 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?

With one parameter at 100% schema coverage the schema already documents review_id as the id returned by veridu_review. The description reinforces that it must be the same id on repeat calls, which is a small semantic addition but not meaningfully beyond the schema, so the baseline 3 applies.

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

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

The first sentence gives a specific verb and resource — check a Veridu review that is still running and fetch its result — and explicitly states the boundary 'never starts a review', which separates it from the veridu_review sibling. An agent can tell exactly which tool handles the in-flight review case without consulting the schema.

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

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

It names the triggering condition (veridu_review returned while the review was still running), the loop instruction (call again with the same review_id), and an explicit negative: do NOT call veridu_review again for the same pull request because that starts a second review and consumes an attempt. That is a full when/when-not/alternative breakdown.

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

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

Beyond annotations, it discloses review behavior, grounding rules, blocking conditions, size limits, follow-up linkage, billing impact, advisory scope, and async response handling. The described idempotent resend behavior is consistent with idempotentHint=true, and the account-usage language is consistent with readOnlyHint=false.

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 dense and front-loaded with purpose and required inputs. Each section covers operational details the agent needs, including limits, follow-up behavior, billing, and async handling, with no obvious 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 complex review tool without an output schema, the description explains the return outcome, findings shape, follow-up fields, and async change_id/stage_label behavior. Together with annotations and the fully described schema, it is complete enough to call 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 coverage is 100%, so baseline is 3, but the description adds substantial meaning for diff and files: exact git diff command, git add -N for new files, full current content requirements, optional related context files, and file-type limits. It also explains parent_change follow-up linking well, though it does not elaborate on intent or repo_name.

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: Veridu reviews a code change before commit or PR. It clearly distinguishes the synchronous review call from the asynchronous sibling get_change by telling the agent to call get_change rather than verify_change again.

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 explicit when-to-use guidance before committing or opening a PR, explains how to call again after fixes, and names the alternative get_change when review is still running. It also addresses parent_change usage and identical resends, leaving little to inference.

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