JIDEC: Bitcoin-anchored public verification ledger (NENRIN)

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

Annotations already indicate read-only, open-world, and idempotent behavior, and the description adds valuable, non-obvious details: fetching exact bytes, recomputing SHA-256 locally, returning integrity and Bitcoin anchoring status, and providing an explicit statement of proof coverage. It also conveys the key trust property that no confidence in HORIZON SHIELD is required, which is beyond any annotation.

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 dense but every sentence contributes something: the inputs, the cryptographic verification process, the output contents, and the trust guarantee. There is no fluff or redundancy, and it is front-loaded with the primary purpose.

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 a single parameter, clear input syntax, and an output schema, the description is still thorough: it explains the response categories by mentioning integrity, anchoring status, parsed record, and coverage statement. It also addresses verification implications and scope of trust, making the tool complete enough for selection and 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?

The input schema already fully documents the citation parameter and lists the accepted formats. The description repeats those formats without adding much beyond making the syntax clearer by using 'bare 64-hex' and 'ledger URL'. This does not materially expand on the schema's coverage.

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: resolve and verify a JIDEC citation, and it explicitly states what that verification entails. It is easy to distinguish from sibling tools like jidec_list_paths or jidec_replay because it emphasizes integrity checking and independent proof rather than enumeration or replay.

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 description gives clear context for when to use the tool: whenever you have a JIDEC citation of any allowed form and need independent verification. It does not explicitly name alternatives or state when not to use it, but the accepted formats and verification purpose effectively convey the intended use.

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 discloses that the tool returns a recipe (a set of steps) and lists the elements it covers. It does not explicitly mention potential errors or edge cases, but given the readOnlyHint and destructiveHint=false annotations, it's clear there are no side effects. The description adds value by clarifying the 'without trusting HORIZON SHIELD' aspect, which is a behavioral trait not covered by 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?

The description is succinct—two sentences—and well-structured. The first sentence states the purpose and lists the included components, while the second gives the usage condition. No redundant words or vague phrases; every sentence earns its place.

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?

Given the tool's simplicity (no output schema, single input parameter) and the read-only nature, the description provides enough context for a user to understand what they will receive (a recipe) and how to invoke it. It doesn't detail the exact format or structure of the returned recipe, but listing the components (bytes, hashes, proof, commit) gives a clear idea. It could mention that the recipe is meant to be followed manually, but that is implied by 'step-by-step'.

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 single parameter 'citation' is well-described in the schema with examples of valid formats ('jidec:path:<sha> | jidec:entry:<n> | 64-hex | ledger URL'), which covers all likely use cases. The tool description does not add further details, but the schema description is already sufficient for understanding what to pass. Since schema coverage is 100%, the baseline is high, and no additional semantics are needed.

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 clearly states the tool's function: returning a step-by-step verification recipe for a JIDEC record without trusting HORIZON SHIELD. It lists specific components (bytes, hashes, proof, commit) and uses a strong verb 'Return'. It also differentiates from sibling tools (cite, list_paths, replay) by focusing on the how-to-verify aspect.

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 description explicitly tells when to use the tool: 'Use this when you want to confirm the result yourself rather than repeat an assertion.' This gives a clear condition for usage and implicitly indicates when not to use it (when trusting the existing assertion is acceptable). It also aligns with the idempotent and read-only annotations, suggesting it is safe to call whenever verification is needed.

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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the ordering behavior ('most recent first') and the included fields, which is useful but not extensive. No contradiction with 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?

A single sentence that front-loads the action and resource, then packs the key output details (ordering, fields, anchoring status) with no wasted words. Every element earns its place.

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-only list tool with a rich output schema and safety annotations, the description is nearly complete. It could have explicitly mentioned that no arguments are required, but the empty input schema already makes that obvious. The output schema covers return values, so the description's job is done.

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 has zero parameters, so the schema provides no parameter semantics to clarify. The description compensates by explaining what the returned list contains (purpose, verdict, Bitcoin anchoring status) and its ordering, which is the only meaningful semantic context an agent needs.

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 ('List') and resource ('anchored JIDEC verification paths'), and adds ordering ('most recent first') plus the fields shown ('purpose, verdict and Bitcoin anchoring status'). It is clear enough to distinguish from siblings like jidec_cite or jidec_replay, though it does not explicitly name a sibling 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 description implies a read-only listing use case, and the sibling names suggest alternatives for citing, verifying, or replaying. However, it does not explicitly state when to use this tool versus those alternatives, leaving the agent to infer the boundary.

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 indicate a safe, read-only, idempotent operation. The description adds valuable behavioral context: it returns MATCH or DRIFT node by node, and nodes that cannot be re-observed are deferred rather than counted as drift. This goes beyond basic safety and explains edge-case handling.

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 three sentences: first states the primary action, second explains the return values (MATCH/DRIFT), and third clarifies the deferred behavior. No filler or redundancy; it is well-structured and front-loaded.

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 a single parameter and rich annotations, the description is fully adequate. It explains the core operation, result interpretation, and an important edge case (deferred nodes). The presence of an output schema further reduces the need to detail return formats.

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 input schema provides 100% coverage for the single 'citation' parameter with clear format examples. The description does not add new parameter-level detail beyond referring to 'anchored path', so the baseline score of 3 applies as the schema handles the heavy lifting.

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 clearly states the tool's function: 'Re-observe an anchored JIDEC verification path against the live system right now and report drift.' It specifies the resource (anchored JIDEC verification path) and the action (re-observe and report), and distinguishes itself from siblings by focusing on drift detection with MATCH/DRIFT output.

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 description provides clear usage context: this tool is for checking current alignment of an anchored path via re-observation. It does not explicitly name alternatives or exclusions relative to sibling tools, but the focus on drift reporting implies when to use it. A 4 reflects clear context without explicit exclusions.

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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds a genuine behavioral nuance in 'as the ledger serves it' — i.e. values are server-authoritative rather than locally recomputed — and points at the recomputation companion tool. It does not mention auth or failure behavior, but for a read tool under full annotation coverage this is solid.

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 front-loaded sentences with no filler; the purpose leads and the companion hint trails. The enumerated return fields are slightly redundant given a full output schema, which is the only minor bloat.

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 tool with a complete output schema and full annotation coverage, the description supplies enough: identity, source of truth, and a follow-up tool. Error handling and pagination are unaddressed but largely inapplicable here.

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?

Single parameter with 100% schema coverage and a schema description ('entry number'), so the schema already carries the semantics. The description's 'ledger entry n' only restates the parameter without adding format, range, or lookup behavior beyond the schema's minimum:1 constraint.

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 ('Return ledger entry n') and describes the shape of what comes back, which distinguishes it from the sibling nenrin_ledger_head (head vs. arbitrary entry). It does not explicitly frame the contrast with that sibling, keeping it just 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?

Offers one usage cue — 'Pair with jidec_how_to_verify to recompute it' — which implies the verification workflow. It never states when to use this over alternatives like nenrin_ledger_head or jidec_replay, so the when-to-use guidance is implied rather than explicit.

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, openWorldHint, and destructiveHint=false, covering the safety profile. The description adds behavioral context by explaining the end marker binding (jidec-head-v1) and the comparison-based detection of truncation/rewrite, which is not in 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?

Two tightly written sentences, front-loaded with the return value followed by the comparative use case. No wasted 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?

With an output schema present, the description need not explain return values in full, yet it still summarises the key returned fields and their purpose. For a zero-parameter, read-only tool, the description is complete enough to call 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?

The tool takes zero parameters, so there is no parameter semantics to explain. Baseline of 4 applies for a no-parameter tool.

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 (Return) and resource (current head of the JIDEC/NENRIN ledger), and enumerates the returned components (entry count n, head hash, end marker with recipe). It does not differentiate from the sibling nenrin_ledger_entry, which likely retrieves a specific entry, so sibling distinction is left implicit.

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?

Provides a clear use case: compare with an earlier head to detect truncation or rewrite. However, it does not name alternatives or state when not to use this tool versus siblings like nenrin_ledger_entry or nenrin_resume.

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 annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, the description adds substantial context beyond that: it explains the content composition, includes cryptographic anchoring and a resume_sha256, and clarifies that 'Absent means no record, not a negative finding.' This is exactly the kind of semantic and interpretative detail an agent needs for a read-only history tool. No annotation contradiction exists.

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 three sentences with no filler, front-loaded with the return action and resource. Every clause earns its place by specifying content, interpretation, or cryptographic detail. It is dense but appropriately sized for a complex read tool.

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?

The description covers what the résumé contains, its cryptographic anchoring, and how to interpret absence, and an output schema exists to carry return-value details. The main remaining gap is usage relative to sibling tools — it does not say when to call this instead of nenrin_witness or nenrin_ledger_entry. Otherwise, an agent has enough to call it 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 100% — the single endpoint parameter includes a clear string description with an example URL. The tool description does not add syntax or format details beyond what the schema already provides. Baseline 3 is correct when the schema does the heavy lifting and the description adds no parameter-level meaning.

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: 'Return the NENRIN résumé of an agent or MCP endpoint' and enumerates exactly what the résumé contains (recorded measurements, Bitcoin-anchored entries, discrepancies, rings, agreements, uncounted records, resume_sha256, recompute recipe). It also explicitly contrasts with a score, which differentiates it from nenrin_trust_signal. An agent can tell this is a history aggregation, not a scoring or single-entry 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?

The line 'A history, not a score' implies the tool should be used when a full conduct history is wanted rather than a trust score, but it never names an alternative tool or states explicit when/when-not conditions. There is no guidance on when to prefer this over nenrin_ledger_entry, nenrin_witness, or nenrin_trust_signal. The usage context is therefore implied rather than explicit.

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, openWorldHint and destructiveHint=false, so the safety and determinism profile is covered. The description adds meaningful behavioral context beyond that: the signal is compact, it deliberately omits a score and refuses to allow or deny, clarifying it is advisory input rather than a decision. It does not mention rate limits or what a missing/low-confidence signal 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?

Two short sentences, front-loaded with the action and payload contents, followed by the crucial negative scoping ('No score, no allow or deny'). Every clause earns its place with no filler.

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 the description need not document the return shape in detail. It covers the action, the input (via schema), the advisory (non-decision) nature, and the intended consumer, which is complete enough for a single-param read-only tool.

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?

Only one parameter, endpoint, and schema description coverage is 100% (a https URL of the agent or MCP endpoint). With zero params the baseline is 4, and here the single param's semantics are already fully documented in the schema; the description adds no additional param detail, which is acceptable given full coverage.

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 clear verb and resource: returns the compact NENRIN signal for an endpoint, enumerating what the signal contains (anchored measurement counts, witness diversity, freshness). Sibling names like nenrin_ledger_entry and nenrin_witness are not explicitly contrasted, so it falls short of 5, but the purpose is unmistakable.

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 description implies the consumer (a trust engine or orderer that reads a compact shape) but gives no explicit when-to-use versus sibling tools, and no when-not-to-use. Usage is only inferable from the phrase 'in a shape a trust engine or orderer can read'.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the state model (pending vs anchored, returning ledger entry and batch), but with an output schema present this largely restates what the schema conveys, so it adds only modest behavioral value.

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, both earning their place: the retrieval semantics come first, the motivating use case second. No filler, though the second sentence could be tighter.

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 one documented parameter, rich annotations, and an output schema, the description only needs to cover purpose and a reason to call it — both are present. Nothing essential is missing for correct 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?

Schema description coverage is 100% and the single field is documented as '64-hex record SHA-256'; the description mirrors that wording without adding format, validation, or error-handling detail. Baseline 3 applies since the schema already does 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?

States a specific verb and resource ('Return one NENRIN witness record') plus the exact lookup key (record SHA-256), which cleanly distinguishes it from sibling ledger tools like nenrin_ledger_entry or nenrin_ledger_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?

Gives an explicit use case — 'check a walk someone says they submitted' — which tells the agent when this tool is relevant. It stops short of naming alternatives or exclusions (e.g., how to list multiple records), so it is clear context without full routing guidance.

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