ruthven

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

Annotations already cover readOnly/idempotent/openWorld, so the description's job is to add what they cannot: it details the response composition (claims with verification states and evidence ids, unknowns, cited records, follow-ups) and sets explicit output boundaries (no valuations, no action recommendations). This is substantive behavioral context, not repetition.

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 tight sentences, front-loaded with the action and scope, then the return contract, then the negative boundaries. Every clause carries information; nothing is padding.

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's enumeration of return fields is essential and well done, and annotations cover the safety profile. It is slightly incomplete on when to prefer this over sibling retrieval/verification tools and on the question parameter's semantics.

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 50%: asset_id carries a rich format description, but question has no description and only a maxLength constraint. The tool description adds nothing about parameter semantics — not the accepted asset_id forms, not the 500-character question limit or what makes a good question — so it fails to compensate for the undocumented half.

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) and resource (a question about one asset) plus the exact scope: single-asset, question-driven. The enumerated return shape (answer, claims, unknowns, evidence, follow-ups) makes it easy to distinguish from siblings like ruthven_get_evidence or ruthven_verify_claim, which return raw records or verification results rather than synthesized answers.

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 'one asset' scope implies when this is appropriate, but there is no explicit guidance on when to choose this over ruthven_get_asset, ruthven_get_evidence, or ruthven_verify_claim. The boundary statements ('never a valuation; never a recommendation to act') constrain output but do not route the agent among 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, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context: the permission model is READ and ANALYSE only, which tells the agent it cannot mutate RUTHVEN state, and it previews the categories of information returned.

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?

A single front-loaded sentence with a colon-delimited inventory of contents — no filler or repetition. The nested list of four items makes it dense but readable; it could be marginally tightened but every clause carries 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?

There is no output schema, so the description must preview the return content, and it does so by enumerating the four sections an agent will receive. For a zero-parameter describe tool with full annotation coverage, that is close to complete; only the format/shape of the returned documentation is left unspecified.

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 takes zero parameters and the schema is fully described, so there is nothing for the description to clarify about inputs. Baseline for a no-parameter tool is 4; no param-specific claims are needed or missing.

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 names a concrete deliverable — a self-description of RUTHVEN covering verification states, permission model, asset types, and JSON API endpoints — so the agent knows this is the onboarding/meta tool rather than a data fetch. It doesn't explicitly contrast itself with the get_/verify_/ask_ siblings, but the enumerated scope is specific enough to separate it from them.

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 only implied: an agent reading 'what RUTHVEN is and what an agent may do with it' can infer this is the orientation call before using ruthven_verify_claim or ruthven_get_asset. No explicit when-to-use, prerequisites, or named alternatives are given, so the guidance remains inferential 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two genuinely non-structured facts: claims carry evidence ids, and include_evidence returns 'the full evidence records as well (large)' — a response-size warning. That is useful but thin; nothing is said about unknown-asset behavior, lookup semantics, or cost, so a 3 is appropriate.

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 with no filler, and the resource identity is front-loaded ahead of the optional-parameter caveat. The long comma-separated field list is dense but each item conveys real content about the payload. Minor cost: the list is slightly encyclopedic for a tool description.

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 carries the burden of describing the return shape, and it does so by enumerating the record's sections and explaining the evidence-id linkage. The read-only/idempotent annotations cover the behavioral side. Missing only error/not-found behavior and any notion of record size for the default (non-evidence) payload.

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%, so both parameters are already documented in the schema (asset id formats, include_evidence default false). The description reinforces include_evidence by flagging the payload as large and explaining that claims reference evidence ids, but adds no new format or constraint detail. Baseline 3 fits when the schema carries the load.

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 enumerates exactly what the record contains (identity, tokenization, provenance, components, hashes, rights, facts, unknowns, counts), which tells an agent this is the comprehensive asset lookup rather than a narrow one. It never states the verb 'retrieve/fetch' and never explicitly differentiates itself from siblings like ruthven_get_provenance or ruthven_get_evidence, so it falls short of a 5.

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 statement of when to use this tool versus ruthven_get_provenance, ruthven_get_evidence, or ruthven_describe. The only guidance-like content is the note that include_evidence=true is 'large', which is a parameter tradeoff, not tool-selection guidance. An agent must infer when the universal record is preferable to the narrower sibling lookups.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds real value by naming what the record contains — read location, hash, state, and freshness — which is exactly the behavioral payload an agent needs and is absent without an output 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?

One sentence, front-loaded with the verb and resource, with the id formats and return contents packed in without filler. Nothing can be trimmed without losing 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?

Two required params with no output schema, and the description describes the returned fields while annotations carry the safety profile, so an agent has enough to call and interpret it. It lacks only explicit sibling routing guidance to be fully self-contained.

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 50%: asset_id's accepted formats are documented, evidence_id's are not. The description compensates for that gap by specifying the EVID-/UNK- prefix forms for evidence_id, so both params now carry usable 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 gives a specific verb and resource ("Retrieve the source record behind a ... evidence id") and even enumerates the two id dialects (EVID-…, UNK-…) it accepts, which distinguishes it from generic retrieval siblings. It stops short of explicitly contrasting itself with ruthven_get_provenance or ruthven_list_evidence, so an agent still has to infer the boundary.

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 by the id-based lookup framing — you call this when you hold a stable evidence id and want the backing record. There is no explicit when-to-use/when-not or named alternative (e.g. list_evidence for enumeration, get_provenance for lineage), so routing rests on 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, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the exact cryptographic pipeline (SHA-256 over the entry, keccak256 up the proof, root compared against the published Passport), the scope limit ('it proves that the record contains the entry; it does not make a statement true'), and determinism with no model involved. It omits auth/prerequisite details, which is minor here.

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 definition is dense but front-loaded: the artifact and its contents come first, the scope caveat and default behavior follow. Sentences are long and clause-heavy, but each carries information that is not duplicated in the schema or annotations.

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 carries the burden of explaining the return value, and it does so well — the proof, the entry, and the steps to verify without trusting RUTHVEN. Combined with 100% schema coverage on inputs, an agent has enough to call it correctly; only the precise response shape and sibling selection remain unstated.

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%, so the schema already documents all three parameters with examples and the maxItems cap. The description only adds the default-behavior case when both optional arrays are absent, which is a behavioral note rather than new parameter semantics. 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 names a concrete artifact (a Merkle proof over evidence records in the issued Origin Passport) and describes its contents: the entry each record rests on plus the verification steps. That is a specific verb+resource, not a restatement of the title. It never contrasts itself with the sibling ruthven_verify_claim, so sibling differentiation is left to the reader.

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 one concrete usage rule — with neither evidence_ids nor paths, the call returns the paths that can be proved — which is genuinely useful routing information. However it never says when to use this tool rather than ruthven_verify_claim or ruthven_get_provenance, so the choice among the proof/verification siblings remains implied.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds useful content-level context by naming what is included (timeline, construction sequence, chain identity, tokenization) and the specific edge types (cut_from, placed_as, pinned_as, pictured_by, hash_of). It does not describe permissions, cost, or the shape/format of the response.

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?

It is a single sentence with no filler, but it is a dense comma-separated dump of return categories with no front-loaded action or guidance. The reader must parse a long list to infer what the tool actually does.

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, so the description bears responsibility for conveying return content — and it does enumerate the categories and relationship types reasonably well. However, it gives no usage routing against the overlapping evidence/proof siblings and no sense of response structure, leaving the definition only minimally 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 100% and the single asset_id parameter is fully documented with accepted formats (PT-0001, RUTHVEN-PT-0000001, work number). The description says nothing about the parameter, so it adds no value beyond the schema; the baseline of 3 applies when the schema does all the work.

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 opening phrase 'Provenance and lineage' names the resource clearly, but the description is essentially an inventory of returned data rather than a statement of what the tool does — there is no verb (fetch/return/compute). It also fails to distinguish itself from close siblings like ruthven_get_evidence or ruthven_get_proof, which overlap with the 'evidence graph' it claims to return.

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 when-to-use guidance, no prerequisites, and no named alternatives. With siblings such as ruthven_get_evidence, ruthven_get_proof, and ruthven_get_asset in the same family, the agent gets no signal for choosing this tool over those.

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, so the safety profile is covered. The description goes beyond them by spelling out the shape of each returned record (stable evidence_id, source types including document/locator/ipfs uri/gateway url/ledger claim id, SHA-256, verification state, freshness timestamps), which is genuinely useful since there is no output schema. It omits pagination behavior despite exposing limit/offset.

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, no filler, and the resource statement is front-loaded ahead of the filtering sentence. The dense field enumeration in sentence one is long but each element carries 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?

With no output schema, the description usefully substitutes by describing the returned record fields, and annotations carry the safety profile. However, for a 7-parameter listing tool it leaves pagination (limit/offset) and the kind/type filter semantics undocumented, which an agent needs to page and filter 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 only 29% and the description does not close the gap. It names the filter parameters and repeats the status enum values already in the schema, but adds no meaning for the undescribed 'kind' and 'type' parameters (and no distinction between them), and never mentions limit/offset, so pagination semantics are absent from both places.

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 names the resource precisely ('the evidence records behind an asset') and enumerates the returned fields, so an agent knows this is a listing/retrieval tool. It does not, however, distinguish itself from close siblings like ruthven_get_evidence or ruthven_get_proof, which is the only thing keeping it out of the top band.

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 only implied: 'Filter by status..., type, kind, or a text query' tells the agent how to narrow results but never says when to pick this tool over ruthven_get_evidence, ruthven_get_proof, or ruthven_get_provenance. No exclusions, prerequisites, or alternative-routing guidance are given.

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, non-destructive and closed-world, so safety is covered. The description adds genuinely new behavioral facts: the operation is deterministic, no model is involved, and it returns hashes, locations and independent verification instructions — exactly the kind of context annotations cannot express. It stops short of stating limits such as the 50-evidence cap or error behavior on unknown ids.

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 tight sentences, front-loaded with the input condition and output contract, with no redundant phrasing. Every clause carries information an agent needs.

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 does the work of describing the return payload (state, hash, location, independent verification path), and annotations cover the safety profile. It is nearly complete, losing only the evidence-count ceiling and any statement about failure modes for invalid ids.

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 50%: asset_id is well documented with its three id formats, while evidence_ids carries no description. The description partially compensates by framing evidence_ids as the evidence a claim rests on and by describing how they are combined (weakest-link), but it never mentions the minItems/maxItems bounds or ordering expectations.

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 names a specific verb+resource ('verify a claim') and adds real semantic detail — it explains the aggregation rule ('the state the claim earns (the weakest among them)') and the returned artifacts. That is far more than a restatement of the title, though it never explicitly contrasts itself with siblings like ruthven_get_evidence or ruthven_get_proof.

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 rather than stated: 'Given the evidence ids a claim rests on' sketches the precondition for calling it, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. use get_evidence for a single record). An agent must infer the routing decision from the description alone.

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