evidence-log

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

With no annotations, the description carries the full behavioral burden. It hints at the payload contents (origin, size, root) but says nothing about read-only nature, authentication requirements, failure modes, or when a checkpoint might be unavailable.

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 minimal waste, but it reads as a grammatical fragment heavy with domain jargon ('witnesses cosign'), which hurts front-loading and parseability.

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 getter with no output schema, the description should explain the return value; it partially does by naming the witnessed fields, but omits format, encoding, and response shape details.

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 of 4 applies; there is nothing for the description to clarify and no ambiguity to resolve.

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 artifact (a signed C2SP checkpoint that witnesses a cosign over origin, size, and root), which implicitly distinguishes it from the proof-based siblings, but it is a noun phrase rather than a clear verb+resource statement. An agent must infer the action ('retrieve') from the name 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 guidance, no prerequisites, and no mention of the sibling tools (get_consistency_proof, get_inclusion_proof, etc.) that an agent might weigh against it. Usage is left entirely 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?

No annotations are provided, so the description carries the full burden. It does disclose meaningful behavior — the prefix property being proven and the default of comparing against 'now' — but says nothing about read-only nature, permissions, rate limits, or what the returned proof looks like. Useful but incomplete for an unannotated tool.

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 defining the proven relation, with the parenthetical default for `second` tucked in efficiently. No filler, though the sentence is dense enough that it sacrifices some clarity for 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?

There is no output schema, so explaining what is returned falls to the description, and it does not cover the shape of the proof object or how to verify it against the two heads. For a cryptographic verification tool among six siblings, the definition is minimally adequate but leaves real 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?

Schema description coverage is 100%, so the schema already documents both `first` and `second`; baseline is 3. The description adds only a marginal detail, that `second` can mean 'now', which is not stated in the schema text but is small added value.

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 cryptographic property: that the tree at size `first` is a prefix of the tree at size `second`, i.e. the log never rewrote history. That is much more informative than a restatement of the name. It does not explicitly distinguish itself from the nearby `get_inclusion_proof` sibling, so it stops 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?

Usage is only implied: an agent can infer this is for auditing a log for rewrite/tamper evidence, and the '(or now)' clause hints that omitting `second` checks against the current head. There is no explicit when-to-use, when-not-to-use, or routing to alternatives such as `get_inclusion_proof` or `get_checkpoint`.

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?

With no annotations, the description carries the full behavioral burden. It does disclose a real invariant (later heads must be consistent with the saved one) and the returned fields, but says nothing about permissions, whether the log must exist, failure modes, or that this is a non-mutating read (only implied by the 'get' verb).

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 zero filler. The resource and its payload are front-loaded, and the preservation instruction follows immediately.

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 compensates by listing the returned fields (tree size, Merkle root, signature) and the consistency contract. For a zero-parameter read tool with no annotations this is close to sufficient, though a note on prerequisites or error behavior would round it out.

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; the baseline for a no-parameter tool applies. The description correctly adds no irrelevant argument discussion.

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 current signed head of the evidence log') and enumerates what it contains (tree size, Merkle root, signature), so an agent knows exactly what it retrieves. It does not, however, differentiate itself from siblings like get_checkpoint or get_ledger_attestation, which sound semantically adjacent.

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 workflow (persist this head to verify future consistency), which is useful context. But it never states when to prefer this over get_checkpoint, get_consistency_proof, or get_inclusion_proof, so the routing decision 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?

No annotations are provided, so the description carries the full disclosure burden. It usefully adds that the proof is 'checkable offline with the public verifier,' which hints at statelessness and no server dependency, but it omits error behaviour (e.g. leaf_index beyond tree_size), whether the proof is tied to a signed checkpoint, and any rate/permission constraints.

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 operation front-loaded and the offline-verification note as secondary value. No filler or repetition, though it is quite terse relative to what an agent might need.

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 read tool with no output schema and no annotations, the description covers the basic contract but leaves the return shape (proof structure, hashes, checkpoint binding) and failure modes unstated. It is adequate but thin for a cryptographic-proof endpoint.

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 both parameters are documented in the schema (leaf_index position, optional tree_size). The description only restates their role ('entry at leaf_index', 'optionally at a given tree_size') without adding format or default semantics, so the 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 states a concrete verb+resource: it returns a proof that the entry at leaf_index is included in the tree, with an optional tree_size scope. It implicitly distinguishes itself from the sibling get_consistency_proof by naming inclusion rather than consistency, though it never explicitly says 'retrieve/returns' or names the sibling.

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 (use this to prove inclusion, and the proof is verifiable offline) but there is no explicit when-to-use guidance, no mention of when to pick this over get_consistency_proof, and no stated prerequisite such as needing a checkpoint or a known tree_size.

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?

No annotations are provided, so the description carries the full disclosure burden. It hints at the return value ('signed head hash'), but says nothing about permissions, whether signing implies tamper-evidence guarantees, or any behavioral constraints of the call.

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 tight sentence with no filler and the key concept front-loaded. It is efficient, though the missing verb makes it read as a label rather than a complete statement of action.

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 annotations and no output schema, the description must convey what the call yields; it does name the signed head hash, which is the core return datum. But it leaves the caller without any sense of format, when the ledger head is relevant, or how it relates to the sibling proof/checkpoint tools.

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 for the description to compensate for. Baseline 4 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 specific resource — the signed head hash of the hash-chained audit ledger — which is more informative than a bare restatement. However, it is a noun phrase with no verb and no differentiation from siblings such as get_evidence_head or get_checkpoint, which likely return overlapping ledger-head material.

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, when-not-to-use, or alternative guidance. With five sibling retrieval tools (get_checkpoint, get_consistency_proof, get_evidence_head, get_inclusion_proof, get_usage), an agent is given nothing to choose between them.

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?

With no annotations, the description carries the full behavioral burden and does disclose that the response is aggregate counts with no per-entity or personal detail ('nothing about anyone'), which is useful data-minimization context. However, it omits whether the operation is read-only, whether it requires authentication, and how the counts are grouped, so substantial gaps remain.

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 a single compact sentence with no filler, and the key idea (recorded volume and external key count) is front-loaded. It is appropriately sized for a zero-parameter tool, though the awkward phrasing slightly reduces clarity rather than wasting 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?

There is no output schema, so the description must explain what the returned counts look like, and it does not: it never says whether counts are totals, per-period, or per-key, nor what 'keys that are not ours' means operationally. For a tool whose entire value is the shape of its numeric output, this leaves the agent guessing.

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 for the description to add. The baseline for a parameterless tool is 4, and the empty schema confirms nothing is 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 gestures at usage counts ('how much is recorded') and a count of external keys ('by how many keys that are not ours'), but it never states a clear verb or resource and reads more like a riddle than a tool definition. An agent can infer it returns aggregate counts, but cannot confidently distinguish its exact scope from siblings like get_ledger_attestation or get_checkpoint.

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, no mention of alternatives, and no exclusions. The only qualifier ('counts only, nothing about anyone') describes output content, not invocation context, so an agent has no routing signal.

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?

With no annotations, the description carries the full burden and does well: it discloses the auth requirement (RiskRouter key in the Authorization header), the irreversibility ('Entries are permanent'), and a privacy constraint ('never the record'). It omits idempotency behavior on duplicate digests and what a successful call returns.

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 short sentences, front-loaded with what is recorded and why, followed by the auth and permanence facts. No filler, and 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 permanent write tool with no annotations and no output schema, the description covers purpose, auth, privacy and irreversibility — enough to call it safely. The main gap is what happens on success or on a repeated digest, which an agent would want before retrying.

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% with only two parameters, so the schema already defines both the 64-char lowercase hex digest and the kind pattern. The description restates the digest input and the 'short kind' but adds no format or constraint detail beyond the schema; 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 — recording the SHA-256 digest of a decision record — and immediately explains the goal (later proving the record unchanged). This is clearly the only write operation among a sibling set that is entirely get_* readers, so no further differentiation is needed.

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 clear context for use: commit a digest now so it can later be shown unchanged, and send the digest rather than the record itself. No explicit when-not conditions or named alternatives, but the get_* siblings make the boundary obvious.

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