agent-trust-oracle

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

Annotations already declare non-read-only, non-idempotent, non-destructive, closed-world behavior, and the phrase "hash-chained" adds real value by implying each call appends a new ledger entry rather than mutating one. However, it does not say whether repeat calls for the same agent each create a distinct attestation, whether permissions or prior registration are required, or what happens on failure.

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 zero filler and the defining trait (hash-chained) placed early. It is efficient but arguably under-specified rather than tight.

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?

An output schema exists, so return values need not be described, but the description still leaves the claim parameter undefined and offers no routing versus verify_attestation or record_outcome. For a two-parameter mutation tool with zero schema coverage, this is thin.

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 0%, so the description carries the full burden and largely fails: "for an agent" loosely implies agent_id, but the claim parameter (defaulting to "reputation-snapshot") is never explained at all. It adds no meaning beyond the bare property names.

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 ("Issue") and a specific resource ("tamper-evident (hash-chained) trust attestation") scoped "for an agent", which clearly separates it from verify_attestation and record_outcome. It stops short of naming a sibling explicitly, so a 4 rather than 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 when-to-use guidance and no mention of the sibling tools it competes with (verify_attestation, record_outcome, score_agent) or any prerequisite such as the agent needing to be registered first. Usage must be inferred entirely from the verb "Issue".

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 useful context beyond that: it is 'free' (no cost/side effects) and it returns the full action-and-input inventory, which tells the agent what to expect from calling it.

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 short sentences, front-loaded with the returned payload and followed by the usage directive. Minor redundancy in restating 'describe this agent' from the name, but nothing wasteful enough to penalize further.

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 discovery tool with an output schema present, the description supplies everything needed: what it returns, that it is read-only and free, and that it should be invoked first. Given the rich annotation set and output schema, no gaps remain.

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, so per the baseline rule this scores 4. The description correctly implies there is nothing to supply by framing the call as an unconditional discovery step.

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 (describe) and resource (this agent) and enumerates the exact content returned: name, version, purpose, supported actions, and each action's inputs. This is unmistakably a self-discovery/meta tool, which no sibling (create_meter, record_usage, sla_report, etc.) duplicates.

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 call-ordering rule: 'call it first to learn how to use this server.' That is strong, actionable when-to-use guidance. It does not explicitly say when not to call it (e.g., after the server capabilities are already known), which is why it falls short of a 5.

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 reads as a pure retrieval, yet annotations declare readOnlyHint=false and idempotentHint=false, and the description offers no explanation of any side effect, logging, or state change that would justify that. It also says nothing about permissions, scoping, or result size/pagination for a 'full history' payload. With output_schema present the return shape is covered, but the non-read-only signal is left unexplained.

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 fragment with zero filler. It is efficient, though the terseness edges into under-specification rather than disciplined brevity.

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-shaped tool with an output schema, the return content is adequately signposted, but the missing sibling differentiation, usage conditions, and any hint about the non-read-only annotation leave real gaps. An agent knows what it gets back but not when to prefer it or what calling it may do.

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 0% description coverage on a single required agent_id, so the description must carry the meaning. 'for an agent' only loosely implies the identifier, but agent_id is self-explanatory by name, so the gap is small rather than harmful.

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 exact payload returned: full outcome history, attestation count, and current score for an agent. That is concrete, but it never distinguishes this tool from siblings like score_agent or describe_agent, which plausibly overlap on 'current score' and agent metadata, so an agent cannot route on the text alone.

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 when-to-use or when-not-to-use guidance and no mention of the sibling alternatives. The agent must infer from the name 'history' that this is the audit-trail view versus score_agent for scoring or record_outcome for writing.

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=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, and the description does not contradict them. It adds genuinely useful behavior beyond annotations: the full set of valid kinds and the fact that security incidents carry a 3x penalty. It does not disclose that records are appended and presumably immutable, nor how weight interacts with the penalty, so there is room left.

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 short sentences, front-loaded with the core action, and the kind list is compact. The inline pipe-delimited enumeration is slightly awkward but wastes no words.

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?

An output schema exists, so return values need not be explained, and the kind enumeration plus penalty note covers the most important semantics. However, with three optional parameters (weight, note, counterparty) completely unexplained and no guidance relative to sibling scoring tools, an agent cannot confidently construct a full call.

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 0% and there are no enums in the schema, so the description carries the full burden. It covers only `kind` (valuably, since the schema has no enum) and gestures at the penalty. The four other parameters — agent_id, note, weight, counterparty — get no explanation at all, leaving most of the surface undocumented.

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: 'Record an interaction outcome for an agent.' That is unambiguous about what the tool does, and the enumerated kinds clarify what an 'outcome' is. It stops short of distinguishing itself from siblings like score_agent or attest, so it lands at 4 rather than 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 call this versus score_agent, attest, or history, and no prerequisites or exclusions. An agent must infer the call context entirely from the name and the kind list. Only the enumeration of valid kinds hints at usage.

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, closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: the score is decay-weighted, bounded to [0,1], accompanied by a tier, and unknown agents receive a neutral 0.5 prior instead of an error or zero.

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 short sentences, zero waste, with the core purpose and return shape front-loaded. The trailing clause about the 0.5 prior earns its place by foreclosing a common agent assumption about missing 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 single-parameter read tool with an output schema, the description covers scoring semantics and the unknown-agent edge case, which is the main ambiguity. The remaining gap is the identifier format and what 'tier' means, both of which an agent could want before calling.

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?

One required parameter (agent_id) with 0% schema description coverage, so the description must carry the burden and only partially does — 'an agent's' implies an identifier but never states whether it is a name, UUID, or DID, or what happens on a malformed value. Baseline is low given the coverage gap.

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 ('Get an agent's decay-weighted trust score') plus the output shape ('in [0,1] and tier'), which is far more informative than the name alone. It does not explicitly contrast itself with siblings like history or verify_attestation, so an agent must infer that this is the read-only aggregate view.

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: the description makes clear you call it to obtain a trust score, but never says when to prefer it over history or describe_agent, nor any preconditions. The second sentence describes edge-case behavior rather than when-to-use 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, and the description's "recomputing its hash" is consistent with that pure-read profile. It does not disclose what happens on a hash mismatch (error vs. boolean result) or what the verification covers, which is the useful behavioral detail 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?

One short sentence, front-loaded with the verb and scope, with no filler or redundant restatement of the 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?

An output schema exists and annotations carry the safety profile, so return values need not be explained. However, for a verification tool the description leaves the parameters unexplained and does not say how a negative result is surfaced, which is a real gap for correct invocation and interpretation.

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 0% and both parameters (`agent_id`, `attestation_id`) are required but entirely undocumented in the schema. The description never clarifies their roles — e.g. whether `agent_id` scopes the lookup or identifies the signer — so it fails to compensate for the coverage gap.

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 supplies a specific verb and resource ("Verify a previously issued attestation") plus the mechanism ("recomputing its hash"), which lets an agent tell it apart from the sibling `attest` that presumably creates attestations. It stops short of naming any sibling explicitly, so differentiation is inferred rather than stated.

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?

"Previously issued" implies the attestation must already exist, so usage context is implied. There is no explicit when-to-use/when-not guidance and no pointer to alternatives such as `attest` or `record_outcome` if verification fails.

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