evidence-log

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 structurally. The description adds real context beyond that: it is a 'signed statement' and a head-relative snapshot, and the final sentence implies the result is meant to be checked for omissions. It stops short of return format, pagination, or auth expectations.

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 padding, with the core object ('signed statement of one completeness chain') front-loaded. The second sentence is metaphorical rather than operational, which costs a bit of efficiency but still carries meaning.

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 properly takes on the burden of describing the return payload: chain length plus per-position leaf, time, and digest. That is unusually complete for a read tool, though it leaves range/pagination behavior of from/to to inference.

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 chain_tag, from, and to are already documented in the schema; baseline 3 applies. The description's 'for each position' phrasing loosely corroborates the from/to range semantics but adds no syntax or edge-case detail beyond what the schema states.

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 resource (one completeness chain) and enumerates what it returns: length plus per-position leaf, time, and digest. The phrase 'as of the current head' pins the scope well, but it never distinguishes itself from close siblings like get_consistency_proof or get_inclusion_proof, which an agent would need to route between.

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 explicit when-to-use statement, no exclusions, and no named alternative among the six sibling 'get_*' tools. The closing line ('A position nobody showed you is a record left out') gestures at significance but is an interpretive remark, not usage 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the return is signed/attested (a 'witnessed' cosign of origin, size, root), which is genuine behavioral context, but it does not address error modes, format details, or response shape. Adds some value over annotations, hence a 3.

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 short sentence with no filler, appropriately sized for a zero-argument getter. The trade-off is that the compression is achieved through unexplained jargon rather than clean wording, but 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?

For a zero-parameter read tool with no output schema, the description is the only place to explain what is returned, and it only partially does so via the cryptic 'witnesses cosign (origin, size, root)' clause. Given no output schema exists, the agent is left guessing at the actual return shape. Adequate but with clear gaps.

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 the baseline is 4. The description mentions origin, size, and root, but these describe the checkpoint's contents rather than inputs, so there is no parameter semantics to add or omit.

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 identifies the resource (the log's signed checkpoint in C2SP format), so the agent knows roughly what it retrieves. However, it is a fragmentary noun phrase with no explicit verb, and it uses dense jargon ('witnesses cosign') that obscures meaning. It gives no signal to distinguish it from siblings like get_consistency_proof or get_evidence_head.

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 indication of when to call this tool versus the seven siblings (get_chain, get_consistency_proof, get_inclusion_proof, etc.). No prerequisites or context for use are stated. The agent must infer the use case entirely from the name.

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 real semantic context beyond them: what the returned proof actually guarantees (prefix/append-only consistency) and that omitting 'second' falls back to the current tree ('or now'). It stops short of noting any response format or verification steps.

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 compact sentence, front-loaded with the guarantee and followed by the plain-language meaning after the colon. Nothing is wasted, though the unquoted parameter names ('size first', 'size second') read slightly awkwardly inside an otherwise tight statement.

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 more of the return-value burden, yet it never says what form the proof takes or how it is consumed (e.g., verified against checkpoints or evidence heads). For a low-parameter cryptographic read tool it is adequate but leaves the agent guessing about the deliverable.

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 goes further by relating the two parameters to each other ('tree at size first is a prefix of the tree at size second') and documenting the default behavior of the optional 'second' via '(or now)', which the schema description ('a later tree size') does not convey.

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 artifact (a consistency proof) and exactly what it asserts: the tree at size 'first' is a prefix of the tree at size 'second'. That is a clear verb+resource equivalent for a proof-generation tool. It does not, however, contrast itself with closely related siblings such as get_inclusion_proof or get_checkpoint, so an agent must infer the distinction.

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 explicit when-to-use or when-not-to-use guidance. The clause 'the log never rewrote history' hints at the verification intent, but the description never names the sibling alternative (get_inclusion_proof for leaf inclusion, get_checkpoint/get_evidence_head for heads), so routing between these near-identical read tools 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 readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: the exact returned artifacts and the append-only consistency property (later heads must be consistent with this one), which is a behavioral trait 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?

Two short sentences, no filler, with the identity of the resource front-loaded and the one actionable instruction placed after it.

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 compensates by naming the returned fields (tree size, Merkle root, signature). For a zero-parameter read tool this is close to complete; only the output encoding/format 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, so per the rubric the baseline is 4; there is nothing for the description to disambiguate.

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+resource (the signed head of the evidence log) and enumerates what it returns: tree size, Merkle root and signature. That is enough to distinguish it from generic siblings, though it never explicitly contrasts itself with get_checkpoint or get_chain.

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?

"Save it: any later head must be consistent with it" implies the intended workflow (capture this head, then verify later heads against it), which is useful implied usage. However, it never says when to choose this over get_checkpoint/get_chain or what the alternative is if the agent wants historical rather than current state.

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 fully covered. The description adds one genuinely useful trait beyond that: the proof is verifiable offline with a public verifier. It does not describe the proof's structure or any error behavior when leaf_index exceeds tree_size.

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 with the core purpose front-loaded and no filler. Nothing is wasted, though the second sentence is a fragment that could be integrated more cleanly.

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 what a 'proof' returns (hash path, root, verification steps), and it only gestures at offline verifiability. It is adequate for selecting the tool but thin on what the agent will actually receive.

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 leaf_index and tree_size are already documented in the schema, including tree_size's optionality. The description only restates those same facts, adding no new format or defaulting detail.

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+resource: producing a proof that the entry at leaf_index is included in the tree. The leaf_index/inclusion framing implicitly separates it from the sibling get_consistency_proof, but the description never names or contrasts that sibling explicitly.

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 guidance on when to call this versus get_consistency_proof or get_checkpoint, and no stated prerequisites. The mention of offline verification hints at intent but does not tell the agent which tool to pick for which task.

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 without the description. The description contributes the fact that the returned hash is cryptographically signed and covers 'recorded quotes', which is meaningful extra context, but says nothing about auth requirements or whether the value changes over time.

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 with no filler, and the key qualifier ('signed head hash') is front-loaded. It is terse to the point of being a fragment rather than a sentence, but nothing in it 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 parameters, no output schema and full annotation coverage, the bar is low, and the description does identify the returned artifact. It still omits any indication of what an agent does with the attestation or how it relates to the sibling proof tools, leaving the integration story incomplete.

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 there is no parameter semantics to explain; the baseline for a no-arg tool is 4. Nothing in the description contradicts or muddies the empty schema.

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 resource — the signed head hash of the hash-chained audit ledger — which distinguishes it from get_chain and get_checkpoint. However it is a bare noun phrase with no verb, so it reads as a label for the payload rather than an action the agent performs. Purpose is inferable but not stated crisply.

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 guidance on when to call this versus the closely related siblings (get_evidence_head, get_checkpoint, get_consistency_proof). The agent must guess whether an attestation is a prerequisite for verification flows or a standalone audit artifact.

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 one genuinely useful trait beyond that: the result is counts only and contains no per-identity data. It says nothing about refresh cadence, aggregation window, or response shape, so the added value is modest.

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 with no filler, and the privacy/scoping note is front-loaded rather than buried. It is arguably over-compressed, trading clarity for brevity, which keeps it short of a 5.

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 parameters and no output schema, the description carries the burden of explaining what comes back. It hints at counts but never specifies what is counted (records? keys? time window?) or the response form, which leaves a real gap for a zero-arg tool whose only value is its return data.

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 there is nothing for the description to disambiguate; baseline 4 applies. Schema coverage is reported at 100% with an empty property set.

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 conveys that this returns recorded volume plus a count of distinct external keys, which reads as usage/statistics retrieval, but the phrasing ('How much is recorded, and by how many keys that are not ours') is oblique and never states a clear verb+resource. It also gives no differentiation from siblings like get_chain or get_ledger_attestation, leaving the agent to infer this is the aggregate-stats 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?

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives among the seven sibling tools. The agent gets a vague sense of what the tool returns but nothing about when to reach for it versus the proof/ledger tools.

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 beyond the annotations by disclosing three things the schema and hints do not: an auth requirement (RiskRouter key in the Authorization header), irreversibility ('Entries are permanent'), and a data-handling constraint ('never the record'). This is exactly the added behavioral context the annotations bar rewards.

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?

Four short sentences, front-loaded with the action and object, then the privacy constraint, then auth, then permanence. No sentence is redundant and none restates the title or name.

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 purpose, auth, permanence, and the critical input constraint for a write tool with no output schema. It does not say what is returned on success (receipt, sequence number, head reference) or cross-reference the chain/checkpoint siblings that consume these entries, which is the remaining gap.

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 explains record_digest, kind, chain_tag, and chain_seq. The description reinforces the meaning of the digest ('SHA-256 of a decision record you keep yourself') but adds no syntax or semantics for the two optional chain parameters. 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?

States a specific verb and resource ('Record the SHA-256 of a decision record') and immediately clarifies the object being recorded is a digest, not the record itself. This cleanly separates it from the sibling get_* tools, which retrieve proofs, heads, chains, and attestations rather than writing.

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 a clear motivation for when to use it: recording now so it 'can later be shown to be unchanged' (i.e., anchor first, verify later via the get_* siblings). It does not explicitly name alternatives or state when not to use it, so it stops short of full routing guidance.

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