Tru8 Evidence Research

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

Goes well beyond the annotations, which only declare readOnly=false, openWorld=true, idempotent=false, destructive=false. The description discloses pricing per tier, that billing follows the tier actually executed rather than requested, a 10-minute dedupe window that prevents double charging on retries, that failures raise errors and are not charged, and that slow runs return a partial {checkId, status, chargedPence, message} payload. These are non-obvious cost and side-effect behaviours an agent must know 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?

Front-loaded purpose, then cleanly sectioned tiers and output structure — appropriate for a tool with this much pricing and fallback complexity. Minor waste: the closing paragraph about docstrings not reaching inputSchema is meta-commentary aimed at tool authors, not at an agent selecting the tool, and pricing is restated between the tier table and the max_tier narrative.

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?

Despite an output schema existing, the description's summary of the nested return shape (claims[].claimMap.elements[], evidenceRefs[], evidence[], _meta) is genuinely useful orientation for a deeply nested payload. Failure modes, partial-return handling, billing semantics and cache staleness are all covered, leaving no obvious gap for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic content: it frames max_tier as a CEILING not a floor via the tier fallback table, and explains that charges depend on the executed tier. It also explicitly notes that per-argument guidance lives in the schema rather than a docstring, which is a useful pointer.

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 combination ('Evidence research for a factual claim or article URL') and immediately clarifies the two accepted input modes. It also names tru8_get_result as the retrieval path for unfinished runs, so an agent can distinguish it from its siblings without opening their 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?

Explicit conditions: submit a claim as text or a URL (auto-detected, triggers article mode with up to 5 extracted claims), set max_tier to cap spend, and use tru8_get_result (free) if the run returns a pending object. The tier fallback order with costs and latencies tells the agent exactly what behaviour to expect at each spend level.

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, covering the safety profile. The description adds the _computed block contents and the differentiation from the raw variant, but does not mention that a still-running check returns status rather than a result (that nuance lives in the parameter schema). This is acceptable but not deeply transparent on its own.

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 each earn their place: the first defines the action, the second enumerates return contents, the third gives usage guidance. No filler, front-loaded, and appropriately sized.

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 rich schema description, annotations, and an output schema present, the overall tool definition is quite complete. The description covers purpose, return contents, and alternative usage; only the polling behavior is left to the schema, which is acceptable. Missing error conditions or permission details, but those are not 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?

The schema has 100% coverage and the check_id description already explains that it's the UUID from tru8_check, mentions retrieval limits, and notes it serves as the poll call. The tool description adds no extra parameter semantics, so 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 description opens with 'Retrieve a previously submitted check with pre-computed analytics', clearly stating the verb and resource. It distinguishes this tool from tru8_get_result_raw by noting it returns structured analytics, making it easy to select the right tool.

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 'Use this over tru8_get_result_raw when you want structured analytics ready for summarisation or comparison without post-processing', providing both a when-to-use condition and a named alternative.

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/destructive annotations, the description discloses valuable behavioral details: exactly which parts are returned (claims, elements, evidence, claim maps), what is excluded (no _computed block), and the consequence (smaller response payload). This gives the agent a clear expectation of the response content.

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 sentences, each earning its place: the first states the core purpose, the second details return contents, and the third gives usage guidance. It is front-loaded with the key action and free of 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?

For a simple one-parameter read-only tool, the description is comprehensive: it explains the action, return contents, and when to use it. The output schema is present, annotations cover safety, and the sibling names provide retrieval context. Nothing important is missing.

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

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

The input schema has 100% coverage; the check_id parameter already has a clear description referencing tru8_check and tru8_get_result. The tool description adds no parameter-specific meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description starts with a specific verb+resource+scope: 'Retrieve a previously submitted check without computed analytics.' It clearly differentiates from the sibling tool tru8_get_result by explicitly stating the absence of the _computed block and smaller payload.

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 when-to-use guidance: 'Use this when you will compute your own aggregations or only need specific fields from the raw data.' It does not explicitly name the alternative tool or state when not to use it, but the context and schema reference to tru8_get_result make the alternative clear.

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