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.