Compaction-loss audit

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

With no annotations, the description still discloses two meaningful traits: the output is an Ed25519-signed receipt and the call costs one metered event. However, it says nothing about whether state is mutated, permission requirements, or failure modes for a tool with nested object input.

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 with the diff action front-loaded and the return value appended. Efficient, though the jargon density slightly reduces immediate legibility.

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 complex tool with 4 params, a nested object, zero schema descriptions, and no output schema, the description is thin. It usefully names the signed-receipt return (compensating for the missing output schema) but leaves parameter roles and call sequencing unexplained.

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 0%, so the description must compensate, yet it only vaguely implies post_text and a snapshot. It never disambiguates the critical snapshot vs snapshot_ref pair, nor explains event_id or why snapshot is a nested object. Only post_text's role is inferable.

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 operation: diff post-compaction context against the pinned snapshot and return an Ed25519-signed receipt. This distinguishes it from siblings like snapshot/pin, though the terms 'post-compaction context' and 'metered event' are dense jargon that assume domain familiarity.

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 word 'post-compaction' implies a timing condition but the description never explicitly says when to call audit versus pin, snapshot, or reinject, nor does it state prerequisites or exclusions. The agent is left to infer the workflow.

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 behavioral burden. It hints at write-time classification and hash-pinning, but does not disclose side effects, idempotency, failure behavior, or what pinning actually changes.

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 front-loaded sentence with little waste. Minor redundancy exists because 'write-time pinning' and 'at write time' repeat the same timing concept.

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 tool with no annotations, no output schema, and an undescribed parameter, the definition is too sparse. It does not explain what the tool returns, what a pinned span becomes, or what an agent should expect after 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?

There is one required parameter with 0% schema description coverage. The description mentions 'ONE span', which loosely implies the text is the span, but it provides no format, size, or validation semantics for the `text` parameter.

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?

It names a specific action cluster (pinning, classify, hash-pin) and scope (ONE span), so the general intent is visible. However, 'span' is undefined and the description gives no clue how this differs from siblings like audit, snapshot, or reinject.

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 phrase 'at write time' gives a temporal context, but there is no explicit when-to-use, when-not-to-use, or alternative-tool guidance. An agent must infer the workflow position entirely.

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 important traits: verbatim restoration, a halt path on critical loss when allow=false, and a signed-receipt requirement. However, it does not explain mutation side effects, what 'critical loss' means, whether changes are reversible, or what a successful response looks like.

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 a single front-loaded sentence with no obvious filler, and the core action appears first. It is dense and uses undefined jargon such as 'spans' and 'critical loss,' but it is not structurally bloated.

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 six-parameter tool with nested objects, no annotations, no output schema, and 0% schema description coverage, the description is materially incomplete. It conveys the high-level purpose and two behavioral constraints, but leaves most parameter semantics and operational details unexplained.

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 must compensate for six parameters. It only partially clarifies receipt (audit's signed receipt) and allow=false, while post_text, event_id, snapshot, and snapshot_ref receive no semantic explanation.

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 and resource: restore degraded/lost spans verbatim. It also states a key conditional behavior (HALT when allow=false), but does not explicitly differentiate this tool from siblings audit, pin, or snapshot.

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 by the phrase 'restore DEGRADED/LOST spans' and the prerequisite that the audit's signed receipt is required. There is no explicit guidance on when to choose reinject versus audit, pin, or snapshot, nor any clear when-not-to-use guidance beyond the allow=false halt behavior.

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 supplied, so the description carries the full disclosure burden, and it mostly doesn't: it does not say whether the operation mutates state, where pinned spans are stored, whether pinning is idempotent or conflicts on duplicate IDs, or what permissions are needed. 'classify + hash-pin' hints at internal processing but explains none of the observable behavior.

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 compact line with the action front-loaded and a parenthetical for the mechanism, so it wastes no space. That brevity, however, edges into under-specification rather than efficiency.

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?

A three-parameter mutation-style tool with no annotations, no output schema, and zero schema coverage needs a far fuller description to be callable with confidence; the current text leaves storage, return behavior, and two parameters unexplained.

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% for three parameters. The description alludes to 'spans' and implicitly to classification, but never explains event_id, pinned_ids, or the expected string format of span entries, so two of three parameters remain fully 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 verb 'pin' and object 'invariants ... spans' are present, but the phrasing is dense jargon and does not distinguish the tool from its sibling 'pin' (nor from 'audit'/'reinject'). An agent can guess it captures something before compaction, but cannot confidently separate it from the near-identically named alternative.

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 only usage cue is the temporal hint 'pre-compaction'. There is no statement of when to prefer this over pin, audit, or reinject, no prerequisites, and no exclusions — the agent must infer all routing from the name alone.

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