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 declare readOnly, idempotent, non-destructive, open-world, so the safety profile needs no restating. The description does add genuinely useful behavioral context beyond them: records may be pending or anchored, and version 0.4 carries the content check as salted-commitment fields with no text — a notable data-availability caveat. It stops short of describing lookup-failure behavior (unknown hash, unanchored record) or output shape details.

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 core operation is front-loaded in the first clause, but the sentence is long and runs three distinct ideas together (record retrieval, how records come to exist, version-0.4 content-check semantics). 'A door writes one before it lets an agent's action run' is helpful framing but sits in the middle of the retrieval explanation rather than being separated.

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 an output schema and full annotation coverage, this is close to complete: it explains what the record is, its lifecycle states, its content-check fields, and where the same data appears in a sibling tool. Missing only failure/not-found semantics and any note on the canonicalization rules the input hash must follow.

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?

With a single parameter at 100% schema coverage, the schema already defines sha256 as a 64-hex canonical digest. The description reinforces that the key must be the *canonical* SHA-256 and that it selects the record as the ledger stores it, but adds no encoding, casing, or normalization guidance.

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 concrete verb and resource — 'Return one admission record (a2a-admission-v0) ... by its canonical SHA-256' — and says what the record contains (exact bytes, pending or anchored state, ledger entry once anchored). It differentiates from nenrin_resume by scope (single record vs. admissions[] listing) and implicitly from nenrin_ledger_entry by nesting the entry inside the record, though the latter relationship is left for the agent to infer.

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 clear by implication: fetch a single admission when you hold its canonical hash; use nenrin_resume when you want a relying party's anchored admissions as a list. The alternative is named explicitly, but there is no explicit statement of when *not* to use this tool or of what to do when the hash is unknown/unanchored.

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 read-only, idempotent, non-destructive, open-world behavior. The description adds meaningful state semantics: the record may be pending or anchored and an associated ledger entry appears only once anchored. It does not discuss auth, rate limits, or not-found behavior, so it is not a 5.

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 compact sentences, front-loaded with purpose and with no filler. The Resume pointer is placed after the primary return behavior, preserving clarity.

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 with an output schema, the definition covers what is returned, the pending/anchored distinction, and the list-view alternative. No critical calling information is missing.

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% and the schema already defines sha256 as a 64-hex canonical SHA-256. The description reinforces 'canonical SHA-256' but adds no parameter format, constraints, or alternative input semantics beyond the schema, so 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 names a specific verb ('Return') and resource ('one agreement record'), ties lookup to canonical SHA-256, and points to nenrin_resume as the list view. It lets an agent distinguish single-record retrieval from list retrieval.

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?

It gives clear context for using this tool when a canonical SHA-256 is known and identifies nenrin_resume for listing anchored agreements. It stops short of explicit when-not guidance or naming nenrin_ledger_entry as a related alternative.

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 read-only, idempotent, open-world, non-destructive, so the bar is lower, yet the description adds substantial behavioral detail: it fetches the record from the ledger and the key from a /.well-known endpoint (explaining the openWorldHint), then recomputes five explicit checks — hash match, closed shape, key listing for heights, Ed25519 verification, and anchor status. It also states the negative guarantee that no content, scope, or answer text is present, which matters for a verifiability 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?

Front-loaded with the return value, then the inputs, then the verification pipeline — a sensible order. The middle sentence is long and compiler-dense ("the shape is closed, the key is listed for the record's heights"), but every clause carries real information rather than 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 return-value detail needn't be spelled out, and the description covers provenance, verification steps, and content-exclusion. What's left implicit is failure behavior — what happens if the record is missing or a check fails — which matters for a verification tool but is arguably carried by the output schema.

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 baseline is 3. The description restates what the schema already says (sha256 as canonical hash, day used when sha256 is absent) and adds only the minor detail that the day lookup goes through the runner's day status. No precedence rules beyond the schema's own wording, no format examples beyond YYYY-MM-DD.

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 the day record (furui-check-day-v0)" and enumerates its contents (signed RFC 6962 root of one UTC day's check envelopes plus their count). An agent knows exactly what comes back. It does not distinguish itself from siblings such as nenrin_furui_leaf or nenrin_ledger_entry, so the sibling boundary must be inferred from the name.

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 invocation paths — "Give its SHA-256, or a day (YYYY-MM-DD)" — and notes the day path resolves "through the runner's day status." That is lookup guidance rather than when-to-use guidance: it never says when this day-level record is the right tool versus the leaf-level or ledger-entry siblings, nor what to do when neither identifier is known.

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 annotations already declare read-only, idempotent, open-world, and non-destructive behavior, and the description adds substantial context beyond that: retention for 7 days, the closed envelope shape, leaf hashing with sha256(0x00 || canonical envelope), audit-path root rebuilding, and Ed25519 signature verification. It stops short of describing error behavior when an envelope is expired, missing, or fails verification.

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 front-loaded with the return action and audit path, then explains the verification steps, and ends with the admission-version context. It is dense but not wasteful; each sentence contributes relevant technical 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?

For a two-parameter read-only tool with full schema coverage and an output schema, the description supplies enough behavioral context about retention and verification. It does not cover failure modes or explicit routing relative to sibling tools, but it is complete enough to invoke 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 coverage is 100%, so the schema already documents both parameters, including the UTC day format and leaf index range. The description adds slight context by saying the day must be closed and the envelope is kept for 7 days, but it does not add syntax or constraints beyond the 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 states a specific verb and resource: return envelope i of a closed UTC day, with its RFC 6962 audit path. It clearly distinguishes a leaf/envelope from broader day or ledger records, but it does not explicitly name a sibling tool or explain when this should be chosen over them.

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 by the reference to a closed UTC day, retention of 7 days, and admissions naming a check by its digest. However, there is no explicit when-to-use guidance, no exclusions, and no direct comparison with alternatives such as the related day or 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?

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?

Annotations already cover read-only, idempotent, open-world, non-destructive, so the safety profile is settled; the description adds real context beyond that: inclusion of outside witnesses 'signed or not', Bitcoin anchoring, discrepancies, and excluded records with reasons. The epistemic caveat that absence is not a negative finding is genuinely valuable behavior an agent could otherwise misread. It stops short of describing cost, rate limits, or response 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?

Purpose is front-loaded and the closing caveat earns its place, but the middle is a dense run-on enumeration of agreements[] and admissions[] fields (record_sha256, ledger entry, decision, content block, revoked) that largely restates what the output schema already provides. Given an output schema exists, that parenthetical detail is redundant weight rather than added value.

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 and full annotations, the description supplies what structured fields cannot: what classes of record appear, what 'anchored' means in context, and how to interpret an empty result. The only gap is the lack of explicit routing guidance against the many sibling 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?

There is a single required parameter whose schema description already gives the type and a concrete example URL at 100% coverage. The description adds nothing about the endpoint parameter itself, so the schema carries the burden entirely; baseline 3 is appropriate for one fully documented 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?

States a specific verb and resource ('Return the NENRIN résumé of an agent or MCP endpoint') and enumerates the content classes it returns, which is enough to tell it apart from record-level siblings like nenrin_ledger_entry or nenrin_admission. It does not name any sibling explicitly, so the differentiation is implied 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?

Usage is implied by the content description (use it to see an endpoint's full recorded history) and the closing caveat 'Absent means no record, not a negative finding' gives useful interpretation guidance. However, there is no explicit when-to-use versus nenrin_trust_signal, nenrin_ledger_head, or nenrin_furui_* alternatives, and 'A history, not a score' hints at a contrast without naming the tool it contrasts with.

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.