Lenz Fact-Check

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

Beyond the readOnly/openWorld annotations, the description discloses that the conversation is kept server-side per verification (statefulness), that calls must be sequential rather than parallel, and that it costs credits at the cheap rate. These are meaningful operational traits an agent cannot get from the annotations alone.

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

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

Front-loaded with the core purpose, then prerequisites, cost, and sequencing constraints in compact order. Every sentence carries information, though a few details (language handling, id type) echo the schema descriptions rather than adding new 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 stateful, credit-costing follow-up tool with an output schema already covering returns, the description supplies everything an agent needs: what evidence it draws on, prerequisites, correct identifier, ordering constraint, and cost. Nothing material 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% and the schema descriptions already carry the key parameter guidance (leave language unset, 500-char limit, verification_id not task_id), so the description largely restates it. Baseline 3 is appropriate since the schema, not the description, does the heavy lifting for parameter meaning.

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 (ask a follow-up question) and resource (grounded in a completed verify_claim result), and explicitly contrasts itself with siblings by noting it reads the FULL evidence the trimmed get_verification payload omits. An agent can distinguish it from get_verification, verify_claim, and assess_claim without opening any 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?

Gives explicit preconditions (only on a completed verify_claim, not assess_claim results), tells the agent which identifier to pass and which to avoid (verification_id from get_verification, NOT a task_id), and adds a sequencing rule (ask follow-ups sequentially, not in parallel). Nothing about when to choose this tool is left to inference.

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

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

Annotations already declare readOnly/openWorld/non-destructive, and the description adds cost (one credit per claim), latency (~15-20s), the model-panel method, the absence of sources ('a first read, not final'), and the confidence-tiered escalation policy. That is substantial 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?

Front-loaded with the core behavior and tightly written, but it is long and restates a few schema facts (the claim/claims exclusivity, the language default) that the schema already documents. Every section is useful, yet there is mild 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 invocation, field semantics, output shape (verdicts, rationale, dissent, recommend_verify, next_step) and escalation. With an output schema present it does not need to exhaustively document returns, yet explains the pieces an agent must act on.

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?

Even with 100% schema coverage, the description supplies operational semantics the schema lacks: a pasted text goes in `claim` whole and unedited, never split or reworded, while `claims` is only for separately listed items, and `language` should be left unset. This materially changes how the agent fills the fields.

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

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

States a specific verb and resource ('a verdict and a bucketed confidence for each factual claim in a text or a list'), plus concrete traits (3-model panel, 15-20s, one credit per claim). It also names the sibling it is not — verify_claim is 'the deep check' — so the agent can distinguish it without opening a 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?

Gives explicit when-to-use triggers ('fact-check this', 'is that true?', 'are you sure?'), explicit exclusions ('not for opinions, predictions, arithmetic or how code behaves'), and a routing rule to verify_claim that varies by confidence tier. Nothing is left to inference.

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

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

Annotations already establish read-only, non-destructive, closed-world, so the bar is coverage of semantics. The description adds genuinely useful behavior: assess_remaining and verify_remaining are two views of ONE balance, spending on one reduces both, and verify_claim costs an order of magnitude more than assess_claim/ask_followup. It does not mention rate limits or failure modes, keeping it short of a 5.

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

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

Front-loaded with the core purpose, and each paragraph earns its place by resolving a real ambiguity (shared balance, price list location, cost ordering). It is slightly long and burdened with escaped/doubled backticks around field names, which is structure noise rather than substance.

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 enumerate return values, yet it still explains the non-obvious shape of costs/cost_options and the shared-balance trap. Combined with annotations covering safety, an agent has everything needed to call and interpret this 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?

Zero input parameters, so the baseline of 4 applies. The description instead explains the returned pricing structure (costs keyed by capability, cost_options nested by parameter/value), which is output-side guidance rather than parameter semantics; no input semantics exist to clarify.

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?

Opens with a specific verb+resource+scope: 'Return the account's remaining Lenz credits, and what they still buy.' It immediately separates itself from the verification siblings by naming the pricing surfaces (costs, cost_options) it's the entry point to.

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 call ('when the user asks about credits, or before a large batch to size it') and, unusually, when NOT to ('It is not a prerequisite: never call it before an ordinary check'). It also routes the agent to costs/cost_options for pricing rather than guessing weights.

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 declare a safe read; the description adds substantial behavior beyond them — the waiting semantics, the three possible status values (completed/needs_input/processing), the supersedes/presentation handling when a deep result replaces an earlier quick verdict, and why no shareable claim-page link is returned (results are private).

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 lead sentence is well front-loaded, but the body is a dense ~180-word block with several stacked parentheticals (the suggested_rewrite caveat, the Lenz-link aside) that are tangential to invocation. Much of the return-field enumeration duplicates the output schema, so not every clause earns its place.

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

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

For a single-parameter read tool with an output schema and full annotation coverage, the description covers everything an agent needs: which argument form to pass, what each status means, how to proceed on non-terminal statuses, and where to send the returned verification_id.

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

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

Schema coverage is 100% and the parameter description already covers the task_id/verification_id duality, so the baseline is 3. The description adds the 8-character length constraint, the wait-vs-immediate behavior tied to each form, and the downstream use of the returned verification_id, giving real extra meaning.

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 (get) and resource (deep verify_claim result) and immediately splits the two modes: wait on a task_id or fetch a completed verification_id. This clearly separates it from verify_claim (which starts a check) and list_verifications (which finds one).

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?

Explicit routing: use task_id to wait, verification_id to fetch immediately; if still processing, tell the user and call again or fall back to list_verifications; if needs_input, present options. It also names ask_followup as the downstream consumer of the returned verification_id.

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?

Goes well past the readOnlyHint/destructiveHint annotations: it discloses that rows appear only after completion, that results are capped at 10 and ordered newest-first, that quick checks are not persisted, what fields each row carries, and that it costs no credits and never starts a check.

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

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

Front-loaded with the core behavior and written in tight sentences that each add information. There is minor redundancy: 'Read-only: it never starts a check' largely restates the readOnlyHint annotation already present in structured data.

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

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

For a zero-parameter, read-only listing tool with an output schema, this covers everything an agent needs: what appears, what does not, ordering, cap, cost, and what to do with the returned id. No further clarification is required.

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 schema has nothing to explain and the baseline is 4. The description instead documents the shape of each returned row and the `verification_id` handoff, which is useful but is output rather than 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?

States a specific verb and resource ('List the user's most recent completed deep checks'), names the producing sibling (`verify_claim`), and constrains ordering and volume ('newest first, up to 10'). An agent can distinguish it immediately from `get_verification` (single full result) and `assess_claim` (quick checks).

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

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

Gives explicit when-to-use triggers: the user asking about an earlier deep check, or a `verify_claim` whose result never arrived after the wait ended. It also states exclusions — running checks are not listed yet, and `assess_claim` quick checks are never stored — so the agent knows when this tool will return nothing.

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=false, destructiveHint=false, openWorldHint=true. The description goes well beyond that by disclosing what actually happens: each claim starts its own deep verification, one claim blocks and returns a result like get_verification with a new task_id, several return one task_id per claim.

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?

Well front-loaded: purpose first, trigger condition second, outcome semantics last. Slightly heavy on backtick formatting and a long final clause, but every sentence carries actionable 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 two-parameter but behaviorally intricate tool, it covers the trigger, valid inputs, and the divergent single- vs multi-claim return behavior. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, and the description largely restates the schema's own wording ('exactly as listed', 'one or more of the offered claim texts'). It reinforces the cardinality and exact-text constraint but adds little that the schema does not already carry.

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

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

States a specific verb and resource ('Resolve a needs_input verification by choosing which claim(s) to run') and clearly distinguishes itself from verify_claim and get_verification, which are named as the producers of the triggering state.

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

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

Gives an explicit trigger condition: when verify_claim or get_verification returns status: needs_input with reason multi_claim, call this with that task_id. It also names the exact source of the claims list, leaving nothing to inference.

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

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

Annotations only establish readOnly=false, openWorld=true, destructive=false; the description goes far beyond by disclosing cost (10 credits vs 1, 5 for depth=low), latency (~a minute to 90s), the completed-vs-submitted status contract, cached-claim behavior, the supersedes/presentation semantics for replacing an earlier verdict, and the caveat that `suggested_rewrite` is not itself verified. That is exactly the behavioral context an agent needs and annotations cannot carry.

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

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

Front-loaded with the outcome and then the routing rule, and every clause carries operational weight (cost, timing, statuses, follow-ups). It is dense and long, and a couple of parentheticals (cache behavior, presentation) could be tightened, but nothing is 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 costly, async-capable, open-world tool with three params and an output schema, the description covers the full decision lifecycle: when to call, what it costs, what statuses come back, which tools to call next for each status, and what must be shown to the user. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it warns that multiple claims in the text return `needs_input` rather than a verdict, and it reinforces that one claim per call is expected. Combined with the schema's own depth/language guidance (cost tradeoff, time saved, when to override language), parameter intent is unambiguous.

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?

Opens with a specific verb+resource ('The deep check: a verdict with a 1–10 score, the key finding, warnings and the main sources for ONE claim') and immediately scopes it against the sibling it is not ('Not the default... a plain "check this" is `assess_claim`'). An agent can distinguish it from assess_claim, get_verification, and select_claims without opening any 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?

Gives explicit when-to-use ('Run only when the user asked for sources, a deep check or a verification, or agreed after a quick check'), when-not ('Never start one unasked'), and the alternative for the default path (`assess_claim`). It also names the follow-up tools for the async and multi-claim branches (`get_verification`, `select_claims`) with their trigger conditions.

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