DERO MCP Server

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description discloses important runtime behaviors: the INVALID_INPUT throw when no input is provided, parallel execution and registry joining, null-output conditions for chain_facts and proof_decode, forge_demo behavior, and CI validation of related_docs. This significantly exceeds what annotations convey and contains no contradictions.

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 long but well-structured with clear section headers ('When to call', 'Input Requirements (CRITICAL)', 'Output'). Each section delivers dense, necessary operational information, and key directives are front-loaded. The verbosity is justified given the composite's complexity and the need to prevent misuse.

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 composite tool with no output schema, the description fully documents the output shape, null semantics, field meanings, and agent behaviors like citing related_docs and quoting context_note. It covers inputs, failure modes, demo forge details, and integration with the false-claim registry, making it self-sufficient 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?

Although schema coverage is 100%, the description adds substantial meaning: at least one of four identifiers is mandatory, exact hash length requirements are clarified, the proof_string format is specified, and include_forge_demo's conditional behavior and demo amount selection logic are explained. This makes the parameter semantics far more actionable than the schema alone.

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 opens with a specific verb ('audit') and a clear resource ('chain artifact... end-to-end'), and states the composite's distinct output: a verdict, chain facts, proof decode, narrative, and rebuttal citations. It explicitly differentiates itself from sibling tools by noting it replaces manual chaining of dero_get_block_header_by_topo_height + dero_get_transaction + dero_decode_proof_string.

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 concrete example questions ('what's going on with DERO block X?', 'is this transaction the inflation-claim TX?') and explicit 'PREFER this over' guidance. It also specifies when include_forge_demo should be true, giving the agent clear decision criteria versus alternatives.

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 and destructiveHint=false, so the safety profile is clear. The description adds behavioral context beyond annotations by explaining that strings are concatenated by the daemon and returned, and that the operation serves as an intact-payload check. This is sufficient for a simple read-only echo 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?

The description is well-structured and appropriately compact: purpose first, then when-to-call guidance, then a critical input requirement, then output. Each section earns its place without fluff or redundant restating of the schema.

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 tool with no output schema, the description is complete: it explains the operation, purpose, usage, critical input constraint, expected output, and alternative sibling. Annotations cover safety and side-effect concerns, so no important guidance 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 of the one parameter is 100%, but the description adds the critical constraint that the array must be non-empty, which the schema does not enforce with minItems. It also clarifies output behavior (strings concatenated by the daemon), going beyond the schema's basic 'Strings to echo back' description.

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?

Description clearly states the action: 'Echo strings through the daemon via DERO.Echo' and identifies it as a round-trip sanity check. It explicitly references the sibling alternative dero_daemon_ping, making the tool's scope distinct.

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 'When to call' section gives a concrete scenario: confirm string payloads reach the daemon intact before debugging malformed calls. It also provides an explicit alternative: 'PREFER dero_daemon_ping for a lighter-weight liveness probe,' clearly indicating when not to use this tool.

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?

Beyond annotations (readOnlyHint, destructiveHint false), the description adds that the tool returns 'Pong' on success and an error with code RPC_UNREACHABLE and retry hint on failure, covering all relevant behavioral traits.

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 compact, using two short paragraphs to convey purpose, usage, input, and output without redundancy. Every sentence serves a clear 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?

Given the tool's simplicity (no params, no output schema), the description thoroughly covers all aspects: purpose, when to use, input, output, and error behavior. No gaps remain.

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?

No parameters exist (0 params, 100% schema coverage), so the description correctly states 'Input Requirements: none.' A score of 4 is appropriate as baseline given zero parameters.

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 action ('connectivity check') and resource ('DERO daemon'), and the tool name 'ping' coupled with the description distinguishes it from siblings like 'dero_daemon_echo' which also tests connectivity but presumably with different semantics.

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?

Explicitly instructs to call as the first step in chain investigations and before get_info if unsure about configuration, providing clear context for when to use this tool versus alternatives.

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 and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: it explains the special meaning of the public key for deroproof strings (derived blinder point, not wallet pubkey), the is_proof flag, the value interpretation with signed/wraparound, and the silent attachment of context_note for flagged artifacts. It also mentions the error code on parse failure. This goes beyond annotations, though it doesn't detail rate limits or auth (not relevant for a read-only decoder).

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 detailed but well-structured with clear sections (When to call, Input Requirements, Output). It front-loads the core purpose and uses bullet-like formatting. It's longer than the calibration examples but every sentence adds value—no fluff. The only minor issue is the length, but it's justified given the complexity of the 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 tool has one parameter, no output schema, and moderate complexity (bech32 decoding with special cases). The description covers the input format, output structure, edge cases (deroproof public key meaning, value interpretation, flagged artifacts), and even suggests related docs to cite. It's complete for an agent to use correctly without further clarification.

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% (the single parameter proof_string is fully described in the schema). The description adds extra semantics: it specifies the required format (full bech32 string with HRP and separator), case consistency per BIP-0173, and that whitespace is trimmed. It also clarifies the parameter is required. This adds value beyond the schema, so a 4 is appropriate.

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 decodes DERO bech32 strings into constituent parts, listing specific HRPs and the special case for deroproof strings. It distinguishes itself from sibling tools by explicitly noting it should be preferred over chaining bech32 decoders and CBOR libraries, and it mentions the exact wire format match with DEROHE rpc.NewAddress.

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 explicit 'When to call' guidance, specifying the use case (user pastes a deroproof/integrated-address string) and explicitly says to PREFER this tool over manual decoding. It also gives critical input requirements and notes when value_interpretation is present, which helps the agent decide when to use it.

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?

Describes the return content (title, headings, plain-text content) and the chunking behavior (60000-char chunks, content_truncated flag, next_offset for pagination). Output field list and semantics are fully explained, leaving no ambiguity about the tool's 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?

Structured with clear sections: purpose, when-to-call, input requirements, output. Front-loaded with the core purpose. Every sentence contributes value; no redundant or vague phrasing. The length is appropriate for the complexity.

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 no output schema, the description fully enumerates the output fields and explains their meaning (content_length, content_truncated, next_offset). It also ties into the broader docs workflow by referencing search and prior citations, covering both typical and edge cases (pagination).

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 covers parameters with details like minLength and enums. The description adds critical behavioral context: slug must be relative to pages/, product is 'RECOMMENDED to disambiguate identical slugs', and offset's chunking protocol is explicitly explained with 60000-char limit and pagination logic. This adds substantial meaning 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 clearly states the verb ('Get') and resource ('a single bundled docs page by slug'), with added context about content type ('plain-text content and headings'). It distinguishes from siblings like dero_docs_search and dero_docs_list by emphasizing the direct retrieval via slug.

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?

Explicit when-to-call guidance: 'AFTER dero_docs_search has returned a candidate slug, OR when you have a known slug from a prior citation. PREFER dero_docs_search first when you only have a topic in mind.' Also covers pagination handling with offset, making usage unambiguous.

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 and destructiveHint=false, so the safe read-only behavior is established. The description adds useful behavioral and output context: default limit of 120, max of 500, and the exact output structure. It does not contradict annotations and covers what an agent needs for a list operation.

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 compact, well-structured with clear 'When to call', 'Input Requirements', and 'Output' sections. Every section earns its place, and the content is front-loaded with the core purpose before additional guidance.

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?

Despite having no output schema, the description documents the return object shape. With only two optional params, read-only annotations, explicit usage guidance, and a complete output contract, the description is fully sufficient for an agent to decide correctness and invoke the 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?

Schema description coverage is 100%, and the description mostly restates what the schema already provides: optional product enum and limit with default/max. It adds context about scoping to one of the four products, but it does not significantly deepen the parameter meaning 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 opens with a specific verb+resource: 'List indexed bundled docs pages across all four products with slugs, titles, and canonical URLs.' It clearly distinguishes the tool from siblings by contrasting it with dero_docs_search and dero_docs_get_page, and names concrete examples like 'what TELA tutorials exist?'

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 an explicit 'When to call' section with concrete use cases: surveying docs, getting a slug catalog before dero_docs_get_page, and preferring dero_docs_search for specific questions. This directly tells the agent when this tool is the right choice and when it is not.

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 include readOnlyHint=true and openWorldHint=false, indicating this is a read-only search over a bounded index. The description goes beyond annotations by explicitly stating 'no network round trip' and describing the ranking output ('ranked matches') and citation preference. It does not mention pagination limitations or whether results are fuzzy, but the annotation coverage reduces the burden.

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 tersely written with bold labels and short bullets, making it scannable. It front-loads the core purpose and in-process nature. A few extra details (e.g., '145+ pages') could be seen as redundant but are informative. No fluff.

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 complex domain (multiple product docs) and 4 parameters, the description covers all necessary aspects: purpose, when to call, input requirements, optional filters, and output structure. No output schema exists, so the description appropriately lists returned fields. It is complete enough for an agent to use 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% for all parameters, with helpful examples in query and valid enum values for product. The description adds context on default limit (8) and scoping guidance (e.g., 'provide a slug prefix'), but these largely mirror the schema. Baseline 3 is appropriate because schema already documents parameter semantics well.

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 begins with a specific verb and resource: 'Search the bundled DERO documentation index across derod, tela, hologram, and deropay.' It also clarifies scope (in-process, no network) and indicates it returns ranked matches. This clearly distinguishes it from sibling docs tools like dero_docs_get_page and dero_docs_list.

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 explicit when-to-use guidance: 'Call this BEFORE explaining DVM, RPC, TELA, Hologram simulator, or DeroPay webhooks.' It also gives explicit when-not-to-use by referencing sibling tools (e.g., 'For docs listing, use dero_docs_list; for page content, use dero_docs_get_page'), and advises returning canonical_url and slug as citations.

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?

Beyond the readOnlyHint annotation, the description discloses the ~10s one-time discovery scan, caching behavior, non-uniqueness of dURLs, newest-contract-wins resolution, collision disclosure, and miss behavior. This is rich behavioral context that annotations alone do not provide.

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 structured with clear sections (composite purpose, when to call, input requirements, output behavior) and every sentence adds value. It is longer than average, but the complexity of collision handling, caching, and routing justifies the length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description fully covers return shapes for hits and misses, including the collision/candidate structure. It also accounts for first-call latency, cache behavior, and downstream routing to tela_inspect, making it complete for this tool's complexity.

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 documents durl with examples. The description adds useful semantics beyond the schema: the parameter is required, case-insensitive, prefix-insensitive, and accepts forms like 'dero://cipherchess.tela'. This raises it above the baseline but is not exhaustive enough for a 5.

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 opens with 'resolve a TELA dURL ... to its on-chain SCID(s)' — a specific verb, resource, and outcome. It also clearly distinguishes this from sibling dero_name_to_address by explicitly noting that non-dURL DERO names belong to that other 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?

Provides explicit when-to-call guidance with concrete user phrasings ('what's the SCID for X.tela', 'find the TELA app called X') and an IMPORTANT routing exclusion for registered DERO names without dots. This is exactly the level of routing context an agent needs to select between this and sibling 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?

The description clearly discloses safety-critical behaviors: it never broadcasts, never touches a wallet, never mutates chain state, and is constructed only from public chain data. It also reveals the self-check behavior and that the tool throws if the forged string cannot verify, which goes beyond the readOnlyHint 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 long but well-structured across purposeful sections: When to call, Math, Input Requirements, Output, and READ-ONLY. Each section carries relevant usage and behavioral detail; minor redundancy appears in the READ-ONLY section restating the annotation, and the overall length is high, but still justified for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description compensates by listing the output fields, their semantics, edge cases, math, self-check behavior, and related docs. It also covers error behavior and negative amount implications. For a complex forgery tool with no schema-level return type, this is fully sufficient.

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 description still adds meaning: it explains the mutual exclusivity in operational terms (daemon fetch vs raw bytes), gives concrete amount examples with negative wraparound, and notes that `ring_receiver_address` is null when `tx_hex` is used. It also highlights a critical constraint not enforced by the schema: exactly one of `tx_hash` or `tx_hex` must be provided.

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 uses a specific verb ('build', 'forge') and clearly identifies the resource: a fresh `deroproof…` string for any transaction, ring slot, and amount. It distinguishes itself from sibling `dero_decode_proof_string` by emphasizing it creates a forged/display proof rather than decoding an existing one.

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 provides an explicit 'When to call' section with a concrete scenario: when a user sees Verified ✓ and asks whether it means the chain minted coins. It also gives a second use case for reproducing the inflation-claim demo. It does not explicitly name exclusion criteria or alternative tools beyond those implied scenarios.

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?

Beyond the readOnlyHint annotation, the description explicitly states the operation is a fetch, details the error condition (providing both or neither hash/height returns INVALID_INPUT), and outlines the returned data structure, making behavior fully transparent.

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 well-organized but slightly repetitive; parameter constraints are restated from the schema. Still, it remains focused and avoids unnecessary fluff.

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?

Covers output fields, prerequisite actions, and error handling. It does not detail the exact format of the response, but referencing dero_docs_search for field semantics compensates. Adequate for an RPC method.

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?

Both parameters (hash, height) are described with constraints (64 hex chars, non-negative integer) in the schema, and the description reinforces the mutual exclusivity requirement. No ambiguity remains.

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 action (fetch a full block) and differentiates from sibling tools like dero_get_block_header_by_hash by explicitly listing the contained fields (header, miner_tx, transactions, topo position).

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 specific when-to-call guidance (investigating a specific block, verifying transaction inclusion) and a prerequisite (call dero_get_height first if height unknown). Lacks explicit exclusions but gives sufficient context.

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 tip count (not topoheight) and the output format. Annotations already indicate readOnlyHint=true, so no contradiction. It adds behavioral context beyond annotations but could mention it's a safe read operation.

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 concise with 5 short sentences, each serving a purpose: definition, distinguishing info, usage guidance, input clarity, and output format. 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?

For a simple tool with no parameters and no output schema, the description provides all necessary context: what it returns, how it differs from a sibling, and when to use it. It is fully complete.

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 zero parameters and 100% schema coverage, the description adds value by stating 'Input Requirements: none,' confirming no inputs needed. This is clear and helpful, earning a baseline 4.

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 'Get the total block count' with a specific verb and resource, and distinguishes itself from the related sibling dero_get_height by indicating that it returns a tip count, not a topoheight. This provides clear differentiation.

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 provides when to call ('when you need just the block count') and when not to ('PREFER dero_get_height when you need tip and stable heights together'), offering a direct alternative sibling.

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 mark this as read-only and non-destructive, and the description adds useful behavioral context: it returns only the header 'without the full block body' and provides the output shape. This is sufficient for a simple read-only RPC call, though it doesn't mention error 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?

The description is compact and well-structured with clear sections: main action, when to call, input requirements, and output. Every sentence contributes either selection guidance, invocation constraints, or expected result, 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?

For a single-parameter read-only lookup with no output schema, the description fully covers what the agent needs: the exact hash format, the reason to prefer this tool over alternatives, and the return shape. No critical context 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%, so the baseline is 3. The description adds value by emphasizing the critical exact 64-hex-character requirement and by giving a practical example of where such a hash comes from (e.g., tx confirmation), which goes beyond the schema's terse 'Block top hash (hex)'.

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 opens with a specific verb-object pair: 'Get a block header by its 64-char hex hash', which precisely states the tool's action and resource. It also distinguishes this tool from sibling dero_get_block by explicitly noting that this variant excludes the full block body.

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 'When to call' section gives explicit guidance: call when you have a block hash and only need the header. It also names an alternative, dero_get_block, for when transactions or miner_tx are needed, making the selection criteria clear.

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 read-only nature is already indicated by annotations (readOnlyHint=true). The description adds semantic context about topoheight being canonical but does not elaborate on error handling, edge cases, or the structure of the returned header. It meets the minimum bar but lacks deeper behavioral insights.

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 well-structured with separate sections for description, when to call, and input requirements. However, it is somewhat repetitive, restating the same information about topoheight in multiple places. Still, the organization aids readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple getter by height, the description covers the essential aspects: what it does, when to use it, and the key input constraint. It does not explain the return structure, but that is not required. The mention of checking current topoheight via dero_get_info adds completeness. Overall, it is sufficient for a tool of this complexity.

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 description enriches the parameter 'topoheight' beyond the schema's basic integer type and min/max. It adds a critical constraint: 'no greater than the current topoheight' and advises to 'call dero_get_info first if unsure.' This is vital for correct usage and not derivable from the schema alone, providing substantial added 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 clearly states the tool's function: retrieving a block header by topological height. It explicitly distinguishes this from other getters (e.g., by hash or chain height) and explains the difference between topoheight and height, making the purpose unambiguous.

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 provides direct guidance on when to use this tool: 'when you need a header keyed by topo position rather than chain height.' This creates a clear contrast with alternative methods and sets expectations for the appropriate context.

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 and destructiveHint=false, and the description adds critical behavioral context: it 'Does NOT submit a block' and explains the response is a 'block template payload suitable for a mining client.' This goes beyond the annotations to clarify the tool's non-mutating nature and output format.

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 concise and well-organized: starts with the core action, then usage guidance, then input requirements, then output and note. No redundant information, every sentence serves a purpose, and key warnings are highlighted with 'CRITICAL.'

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 tool is simple (3 params, no output schema), and the description covers purpose, usage, all inputs, output nature, and a critical note about submission. It provides everything an agent needs to correctly call and interpret the tool without missing critical information.

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?

Despite 100% schema coverage, the description enriches each parameter: it states wallet_address MUST be a valid DERO address with specific prefixes, clarifies that block is optional and its effect ('include the raw block blob'), and labels miner as 'Optional miner id / label.' This adds practical guidance beyond the schema definitions.

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: 'Get a mining block template for a miner payout address' and explicitly distinguishes it from sibling dero_get_last_block_header by advising to prefer that for general chain-tip inspection. The verb 'Get' with resource 'mining block template' is specific and unambiguous.

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 explicit when-to-call guidance: 'ONLY when you are actually mining' and points to an alternative tool for other scenarios: 'PREFER dero_get_last_block_header for general chain-tip inspection.' This directly helps the agent choose the correct tool.

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 critical behavioral traits beyond annotations: 'this returns an opaque encrypted blob, NOT a cleartext balance. Only the wallet holding the spend key can decrypt it. Do NOT present the encrypted bytes as a balance.' This is valuable context that the readOnlyHint annotation alone does not convey. It also documents the output structure, further enhancing transparency.

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 well-structured with clear sections: purpose, CRITICAL warning, when to call, input requirements, and output. It is front-loaded with the core purpose and every sentence adds value. The formatting uses headers and capitals effectively to guide the agent without excessive verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description appropriately documents the output shape: '{ status, registration, balance (encrypted blob), ... }' and explains the encrypted nature. It covers purpose, behavior, usage context, input constraints, and output, making it fully self-sufficient. The annotations further support the read-only, non-destructive nature, so no gaps remain.

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 reinforces the schema by highlighting 'address MUST start with dero1/deto1', 'topoheight MUST be an integer; use -1 for latest chain tip', and 'scid optional'. However, it adds little new semantic information beyond what the schema already states; it mostly re-emphasizes criticality rather than introducing new details.

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 specific action: 'Get the ENCRYPTED balance blob for a DERO address at a topo height via DERO.GetEncryptedBalance.' It explicitly differentiates this from a cleartext balance, distinguishing it from potential sibling balance-related tools. The verb+resource pair is precise and unambiguous.

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 an explicit 'When to call' section: 'when verifying that an address has on-chain encrypted state... or as a sub-step in another tool.' It also advises referencing dero_docs_search for user understanding. However, it does not explicitly mention when NOT to call or name alternative tools for cleartext balance retrieval, so it misses the full when/when-not/alternatives combination.

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, and the description reinforces with 'PRE-FLIGHT check; nothing is submitted.' It adds no contradictory info and provides a specific behavioral guarantee beyond the annotation, though it could mention that it never modifies state beyond what's implied.

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 well-organized with clear sections (purpose, when-to-call, input requirements, output) and uses formatting to emphasize critical input rules. It is longer than the absolute minimum but every sentence adds value; the 'CRITICAL' label highlights a key constraint without fluff.

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 purpose, usage context, all input parameters with critical requirements, and explicitly states the output format ({ gascompute, gasstorage, status }). Given the tool's complexity and lack of output schema, this is complete and self-sufficient for an agent 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?

While schema coverage is 100%, the description adds crucial context: the constraint that at least one of transfers/sc/sc_rpc must be provided, detailed explanations of sc (DVM-BASIC contract source) and sc_rpc (array of {name, datatype, value}), and the preferred nature of signer. This goes beyond the schema's terse descriptions.

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?

Clearly states the tool estimates gas (compute + storage) for three distinct operation types (transfers, SC deploys, SC invokes) via DERO.GetGasEstimate. This is specific and differentiates from siblings like estimate_deploy_cost by covering a broader scope, though it doesn't explicitly name alternatives.

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 explicit when-to-call guidance: 'BEFORE any wallet-side transfer/scinvoke... to size fees, OR when explaining deploy costs to a user.' Also suggests preferring dero_docs_search for user-facing explanations, setting clear usage context without ambiguity.

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 and destructiveHint=false, so the agent knows it's safe. The description adds that it's a 'quick' snapshot and specifies the output fields, providing useful but not critical context beyond 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?

Four concise sentences with no fluff: purpose, usage guidance, input requirements, and output format. Highly efficient.

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 zero parameters and a simple output, the description fully covers what the tool does, how to use it, and what to expect. It even references the sibling tool. No major gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, and the description states 'Input Requirements: none', which is clear. Schema coverage is 100% so no additional information is 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 it retrieves current block heights (tip, stable, topoheight) via DERO.GetHeight. It uses a specific verb 'get' and resource 'block heights', and distinguishes itself from the sibling 'dero_get_info' which provides more data.

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?

Explicitly tells when to call ('when you need a quick height snapshot without the full chain-info payload') and when not to ('PREFER dero_get_info when you also need network, version, or difficulty'). This is excellent guidance with alternative naming.

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 and destructiveHint=false, so the description adds value by specifying the output fields and confirming no input requirements. It does not contradict annotations and provides additional context about the tool's behavior beyond the structured fields.

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 concise (about 6 sentences) and well-structured with clear sections: purpose, when to call, input, output. Every sentence adds useful information without redundancy.

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 has no parameters and no output schema, the description fully covers the output fields and usage context. It includes guidance on when to use and what data to expect, making it complete for an agent 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?

The tool has zero parameters, and schema coverage is 100%. The description states 'Input Requirements: none,' which is sufficient. No additional parameter documentation is 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 returns DERO daemon and chain metadata, listing specific fields (height, topoheight, etc.), which distinguishes it from siblings that operate on blocks, transactions, or smart contracts.

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?

Explicitly says when to call: 'first thing in any chain-state investigation or sync-health check' and instructs to call before other chain-related tools like dero_get_sc, dero_get_transaction, or dero_get_block. Also suggests citing dero_docs_search for verification, providing clear guidance on usage context and alternatives.

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 and destructiveHint=false, so the description adds value by specifying the scope (block header only) and output fields (hash, height, etc.), which is clear and non-contradictory.

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 concise with clear sections (purpose, when to call, input, output). Each sentence adds value, no superfluous content.

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 no required inputs and no output schema, the description provides a representative output snippet and covers all relevant context for a simple 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?

No parameters exist, and the description explicitly states 'Input Requirements: none'. Since schema coverage is 100%, and the description adds no redundant info, baseline 4 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states it retrieves the header of the current tip block via DERO.GetLastBlockHeader and clearly distinguishes it from dero_get_block by noting it returns no full block body.

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 explicit guidance: 'When to call' describes scenarios for tip block metadata without transactions, and recommends dero_get_block when transactions are needed, differentiating from a sibling tool.

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 and destructiveHint=false, and the description adds useful semantics: addresses are random, registered, and scid limits sampling to asset holders. The non-idempotentHint is consistent with 'random'. 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?

Well-structured with purpose, when-to-call, input requirements, and output shape. It is concise and easy to scan, though there is slight redundancy with the schema pattern and the implementation detail 'via DERO.GetRandomAddress' adds limited 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 simple read-only tool with one optional parameter, the description fully covers invocation context, parameter behavior, constraint, and output format. Strong annotations further reduce the need for additional safety or side-effect disclosure.

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 already enforces the 64-hex pattern. The description adds meaning beyond the schema by explaining that providing scid 'limits sampling to holders of that asset,' which is the key behavioral effect of the 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?

The description clearly states the tool's function: 'Get random registered addresses from the chain' for ring construction in private transfers. This specific verb+resource combination distinguishes it from sibling getters like dero_get_transaction or dero_get_block.

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 explicit 'When to call' guidance: building a transfer ring in external wallet tooling or sampling chain participants. It gives clear context but does not explicitly mention when not to use it or name alternative 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?

While annotations already declare readOnlyHint=true and destructiveHint=false, the description enriches understanding by detailing default behaviors for 'code' and 'variables' (both default true), how to skip them for efficiency, and the meaning of omitting or using -1 for 'topoheight'. It also discloses the output shape, which is absent from annotations or schema. No contradictions exist; the description complements the annotations perfectly.

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 longer than typical but exceptionally well-organized with clear headings: 'Input Requirements (CRITICAL)' and 'Output'. Every sentence adds value: usage context, defaults, and output shape. While it could be considered verbose for a simple getter, the complexity of the tool justifies the length. No fluff; each line is functional.

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 there is no output schema, the description compensates by defining the return structure ('{ code, balances, variables: { stringkeys, uint64keys }, ... }'). It also covers default behaviors, parameter edge cases (omitting topoheight), and practical usage tips. For a tool with 4 parameters and no output schema, this description leaves no critical information gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description repeats parameter purposes but adds minimal new semantic detail beyond schema descriptions; it does clarify the default values and the '-1 for latest' convention for topoheight, which is also in the schema. The output format note is helpful but not parameter-specific. Thus, it meets but does not exceed the baseline.

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 opens with a specific verb+resource: 'Read smart contract state (code and/or stored variables) by SCID'. It immediately distinguishes itself as 'the primary entry point for any contract inspection on DERO,' clearly differentiating it from sibling tools like 'dero_get_transaction' or 'explain_smart_contract'. No ambiguity about what the tool does.

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?

Explicitly states when to call: 'as the first step in any DVM contract investigation.' It also gives guidance on complementing with dero_docs_search for interpretation, and even instructs to prefer citing docs pages. This goes beyond basic usage and provides a clear decision path, covering both when and how to use the tool effectively.

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 and destructiveHint=false. The description adds behavioral output details: per-transaction confirmation status, block hash, decoded JSON option, and the `{ txs, txs_as_hex }` response shape. No contradiction with annotations; a bit more on error/not-found behavior would push it higher.

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 core purpose, then organized into When to call, Input Requirements, and Output sections. Each sentence contributes either selection guidance, parameter semantics, or return-value context without padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by stating the output shape and per-tx fields. It also covers both parameters, the optional decode behavior, and the companion tool relationship, making it sufficient for an agent 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 baseline is 3. The description adds value by stressing txs_hashes MUST be a non-empty array of 64-char hex strings and by explaining decode_as_json should be set to 1 (any non-zero) to receive JSON-decoded fields instead of raw blobs.

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?

Description opens with 'Fetch one or more transactions by hash via DERO.GetTransaction,' a specific verb+resource+scope. It distinguishes from sibling lookup tools by emphasizing hash-based transaction tracing and one-or-more batch capability.

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?

Explicit 'When to call: when tracing a tx by hash' gives clear use context, and it names companion tool dero_get_sc for contract-invoking transactions. It also recommends dero_docs_search for interpreting fields, providing actionable guidance beyond the schema.

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 and destructiveHint=false. The description adds valuable behavioral detail about possible null/empty tx_hashes, but doesn't disclose other traits like rate limits or pagination, which are not needed for this simple 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?

Extremely concise: three short paragraphs covering purpose, when to call, input/output. Every sentence adds value. Front-loaded with the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters, existing annotations, and no output schema, the description fully covers the tool's behavior, output format, and edge cases. Nothing 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?

No parameters exist, so baseline is 4. The description correctly notes 'Input Requirements: none' and schema coverage is 100% (vacuous). No further parameter info 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 'List pending mempool transaction hashes' using a specific verb and resource, distinguishing it from sibling tools that deal with blocks, transactions, or other data.

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 explicit when-to-use scenarios: 'when checking unconfirmed activity, watching for a specific tx to land, or estimating mempool pressure.' Also explains how to handle null/empty response.

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 readOnlyHint=true, so the description adds extra behavioral details like case-sensitivity and the meaning of topoheight=-1 beyond the annotation. It does not contradict 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 extremely concise, with no redundant information. It follows a clear structure: purpose, when to call, input requirements, output. Every sentence adds 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?

The description covers the input parameters, the output format, and the error case (NOT_FOUND). It is sufficient for an agent to use the tool correctly without needing further context.

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 covers types, requirements, and descriptions. The description adds semantics like the case-sensitive resolution and the special value -1 for topoheight, which go 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 clearly states the action (resolve) and the resource (DERO registered name to address). It distinguishes from sibling tools by focusing on name resolution, which is unique among the listed tools.

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?

Explicitly states when to call: when a user supplies a human-readable name instead of an address. Also provides detailed input requirements (non-empty string, integer topoheight, -1 for latest), giving clear usage context.

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?

Despite annotations declaring readOnlyHint=true and destructiveHint=false, the description adds significant behavioral context: it discloses the composite nature (in-process scan of newest contracts), the one-time ~10s discovery scan on first call, and that index_meta reveals scan coverage for transparency. This goes beyond what annotations provide, enhancing understanding of performance and data scope.

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 appropriately sized, front-loaded with a clear purpose, and structured into logical sections (What it does, When to call, Input Requirements, Output). Each section is concise and information-dense, with no wasted words or repetition of schema details unnecessarily.

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 tool has only 2 parameters (both covered), good annotations, and no output schema. The description compensates well by outlining the output structure, mentioning the index_meta coverage disclosure, and the caching behavior. It doesn't elaborate on return fields' semantics, but that's minimal gap given the simple output.

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% for both parameters, so baseline is 3. The description adds value by explaining the query parameter's matching scope (against dURL and name, case-insensitive) and examples, and confirming the limit's default and max, which reinforces but also slightly exceeds schema details. It doesn't introduce new info but effectively clarifies usage.

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 purpose: to list and browse TELA apps discovered on-chain, with specific fields (dURL, name, SCID, doc count). It directly addresses the user question 'what TELA apps exist?' and differentiates from siblings by mentioning 'without any external indexer' and providing explicit alternatives (dero_durl_to_scid, tela_inspect).

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 explicit when-to-call scenarios ('when a user wants to explore or search the TELA ecosystem...') and explicitly names alternatives for different needs (exact dURL -> dero_durl_to_scid; inspect specific SCID -> tela_inspect). It also gives input requirements, clarifying that query is optional and for filtering.

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?

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description discloses partial-failure handling, the status enum, null conditions for chain and mempool, and the RPC_UNREACHABLE error code. It adds substantial behavioral context without contradicting 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 well-structured with clear sections (summary, when to call, input requirements, output) and every sentence provides necessary information. It is appropriately sized for the tool's complexity, front-loading the core purpose and usage.

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 composite tool with no output schema, the description thoroughly details the output structure, status values, null conditions, and error handling. It also covers usage context and failure modes, making it complete for the tool's complexity.

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 include_tx_pool has 100% schema coverage, and the description adds usage context (set false when only chain-tip status is needed) and default behavior, going beyond the schema's minimal description. This enriches parameter understanding.

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 it is a composite tool that runs a four-step chain (DERO.Ping → DERO.GetInfo → DERO.GetHeight → DERO.GetTxPool) and returns a health report, distinguishing itself from the primitive sibling tools. It uses specific nouns and verbs, making its purpose 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?

Explicitly states when to call (as first step in chain-state investigations for health/sync/state questions) and provides a clear preference over chaining primitives, with reasons (handles partial-failure modes, consistent lag classification, cites docs). This gives strong guidance on usage and alternatives.

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?

Beyond the readOnlyHint annotation, the description discloses failure behavior: no fabricated breakdown when daemon returns 0/0 with non-OK status, null breakdown conditions, and structured _meta.error with INVALID_INPUT. It also explains the composite's reuse of extractScSurface and its protective role.

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 long but well-structured with clear sections: composite behavior, when to call, input requirements, and output. Each sentence contributes non-obvious operational detail such as defaults, failure modes, and output shape; nothing feels redundant or 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?

With no output schema, the description provides a thorough output shape including estimate, breakdown, signer_used, include_breakdown, sc_surface, and related_docs. It also covers edge cases like compile failure and null breakdown, making the tool safe and understandable for an agent.

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 description adds substantial semantics on top: sc must contain at least one Function...End Function block and a function body alone fails with INVALID_INPUT; signer provides fee context but omission still yields a meaningful estimate; include_breakdown default true with a concrete use case for setting false.

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 composite action: send DVM-BASIC source to the daemon's gas estimator and return raw estimate, breakdown, contract surface, and docs citations. It clearly distinguishes itself from sibling tools like dero_get_gas_estimate and explain_smart_contract by framing itself as a composite with added explanation and failure protection.

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 explicit when-to-call guidance: BEFORE asking a wallet to broadcast a deploy transaction, or when explaining contract cost to a user. It also explicitly says PREFER this over chaining dero_get_gas_estimate yourself, naming the alternative and giving a concrete reason.

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?

Beyond the read-only annotation, the description discloses significant behavioral details: it parses DVM-BASIC source, detects TELA contracts first, handles unknown SCIDs by setting has_code false and providing explanatory narrative, and always includes raw_code_length so the agent can decide when to call dero_get_sc. These details meaningfully extend beyond 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?

The description is well structured and front-loaded with the composite result, followed by when-to-call, input requirements, and output shape. It is appropriately detailed for a complex tool with no output schema, and every section 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?

With no output schema, the description provides a complete output contract, including field names, possible kind values, shape of surface functions, and behavior for unknown SCIDs. It also addresses the one likely failure mode (has_code false) and tells the agent when to fall back to dero_get_sc.

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?

Even though the schema covers 100% of parameter descriptions, the description adds valuable practical guidance: scid is required and must be 64 hex chars, with a known-good example `0000…0001`; topoheight is optional for inspecting a specific height and omitted for latest. This exceeds the schema's bare descriptions and helps the agent choose and format values correctly.

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?

Description uses a specific verb and resource: 'fetch a DERO smart contract' and returns a well-defined surface ('function surface, classification, narrative, curated docs citations'). It clearly distinguishes from siblings like dero_get_sc and tela_inspect by calling itself a composite and naming a fallback.

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 'When to call' section explicitly states the intended use case ('user wants to UNDERSTAND a smart contract') and recommends preference over chaining dero_get_sc with a docs lookup. It also gives a direct alternative ('for a deep TELA parse use tela_inspect') and a fallback to dero_get_sc for full source.

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?

Discloses rich behavior beyond annotations: parallel search across products, 1.5× boost for product_hint, deduplication, rationale per result, pre-built citations, and structured error code on no matches. The readOnlyHint=true annotation is consistent with the description, and the description adds valuable details about internal processing and error 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?

Though fairly long, it is logically structured with headings (When to call, Input Requirements, Output) and front-loaded with purpose. Every sentence adds value—no fluff. For a complex composite tool, this level of detail is necessary and well-organized.

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 complexity (composite, parallel processing, product hint, ranking), the description comprehensively covers usage, parameters, output structure, and error behavior. No output schema exists, so the detailed output explanation fills that gap. It also clearly differentiates from many sibling tools, ensuring correct tool selection.

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?

Input schema coverage is 100%, but description adds significant guidance: for intent it advises dropping verbs and provides examples; for product_hint it explains the multiplication factor and effect on ranking; for limit_per_product it notes the default and behavior. This exceeds the baseline of 3 for full schema coverage by adding practical usage nuances.

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 clear purpose: a composite search tool that runs parallel queries across all four DERO products and returns ranked recommendations. It explicitly differentiates from sibling dero_docs_search by noting it should be preferred over guessing the product, and it describes the output format with rationale and related_docs.

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 explicit when-to-call guidance: at the start of any 'where do I read about X?' investigation, before calling dero_docs_search. Also explains when to pass product_hint (when user mentions a product) and that it should be preferred over guessing, effectively telling when not to call alternatives.

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 and destructiveHint=false, but the description adds substantial behavioral context: the file lives in a DVM-BASIC comment block, gzip files are decompressed, large files paginate, and signatures are reported but not cryptographically verified. 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?

Although long, the description is well-structured with clear sections: composite behavior, when to call, input requirements, and output breakdown. Every sentence adds operational value, and the structure aids quick scanning despite the high level of detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description fully compensates by enumerating the entire output object, explaining content chunking, pagination, compressed/decompressed states, stored_filename semantics, docType, signature presence, and edge cases like DocShard/STATIC/external content. This is complete for a complex 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?

Despite 100% schema coverage, the description enriches each parameter: scid is required and invalid inputs get INVALID_INPUT, offset is linked to next_offset pagination, and topoheight should be omitted for latest state. It also clarifies expected types and failure behavior beyond schema definitions.

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: 'fetch the actual file content stored in a TELA-DOC-1 contract.' It clarifies the composite nature (fetches DERO.GetSC, confirms SCID, extracts bytes) and distinguishes itself from sibling tools like dero_get_sc and tela_inspect.

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 explicit 'When to call' guidance, explains how to obtain SCIDs via tela_inspect, and directly contrasts with dero_get_sc: 'PREFER this over dero_get_sc: that returns the raw DVM contract wrapper; this extracts just the embedded file content.' This is exemplary usage guidance.

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?

Beyond the readOnlyHint annotation, the description reveals the auto-detection logic, the possibility of a 'not_tela' return for non-TELA contracts, and the caveat that updateability cannot be derived from chain state. This provides full transparency about expected behavior without contradicting 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 excessively verbose and repetitive. The output format is described in full detail twice (once in the main description and again in the 'Output' section), and the rationale for preferring this tool is restated multiple times. While organized into sections, the redundancy inflates length without adding 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?

The description covers all relevant aspects: purpose, usage criteria, input requirements, detailed output structure (including the discriminated union variants), and edge cases like 'not_tela'. It also provides the necessary background on TELA standards and why this tool is superior to generic alternatives, making it complete for agent decision-making.

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 parameter descriptions in the schema already cover the meaning and constraints (64-char hex, topoheight optional for latest state). The tool description repeats this information without adding new insight, though it does reinforce the context of TELA contract types. Given high schema coverage, this is adequate but not additive 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 clearly states that the tool fetches and parses TELA contracts, auto-detecting between INDEX and DOC types. It explicitly distinguishes itself from sibling tools (dero_get_sc, explain_smart_contract) by explaining their limitations, making the purpose unambiguous.

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 provides explicit when-to-use instructions (first step for TELA SCIDs, .tela dURL apps, specific user queries) and directly states preference over alternatives. It also includes input requirements (scid required, topoheight optional) and clarifies the 'not_tela' fallback case.

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 declare read-only, non-destructive. Description adds the empty-record failure mode (TX_NOT_FOUND), clarifies SC invocation arg decoding is NOT performed, and tells the agent the raw hex is still available. Very transparent about boundaries.

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?

Long but front-loaded with purpose and when-to-call. Every sentence adds context (failure modes, parameter rationale, output details). Slight redundancy (SC-doc notation appears twice) but overall efficient.

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?

Complex composite tool with no output schema, but description documents output structure, failure modes, defaults, and limitations thoroughly. Agent has everything needed to decide when and how to call.

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 baseline is 3. The description adds usage semantics for decode (informational view, raw hex still available) and include_sc_context (skip for performance), which goes beyond the schema. So it's a 4.

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?

Description opens with a precise composite action: 'look up a DERO transaction by hash, classify its confirmation status... extract the SC surface inline... stitch docs pages as citations.' It clearly distinguishes from chained alternatives by naming the exact tool pair it replaces. Users know exactly what this tool does.

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?

Explicit 'When to call' section states use as FIRST step for tx-hash queries. It also explains when NOT to use the composite and to prefer the chained approach for non-install txs. This is ideal guidance.

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 declare readOnlyHint=true, and the description adds rich behavioral context: it explains the semantic distinction between the recomputed supply and GetInfo's potential undercount (display quirk), the error behavior (RPC_UNREACHABLE / INVALID_INPUT) when the daemon is unreachable without height, and the output structure including `match` being null when GetInfo isn't present. 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?

The description is well-structured with clear sections (purpose, when to call, input requirements, output). Each sentence provides essential information without redundancy. It front-loads the primary purpose and then details usage and edge cases. Despite its length, it is concise because every segment adds necessary context.

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?

No output schema is provided, so the description fully compensates by enumerating all output fields and their semantics (e.g., `match` true/false/null). It also clarifies the scope ('schedule CalcSupply only — NOT a UTXO census') and mentions related_docs, giving the agent a complete understanding of what to expect and how to handle the result. Given the tool's complexity, this is a complete description.

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% for the single parameter `height`, and the schema already documents its type and default. The description adds the failure condition ('If the daemon is unreachable you MUST pass height — otherwise the tool returns RPC_UNREACHABLE / INVALID_INPUT'), which is beyond the schema's wording and clarifies the consequence of non-compliance. This minor addition lifts the score above the baseline 3.

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 purpose: recompute DERO total supply via CalcSupply, optionally cross-checking with DERO.GetInfo.total_supply. It uses a specific verb ('recompute'), names the exact method (CalcSupply) and data sources, and distinguishes itself from sibling tools like dero_get_info by noting the GetInfo undercount quirk. The composite nature is clearly defined.

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 lists trigger phrases ('what is the total supply', 'does GetInfo match the schedule', 'verify the supply') and states when to use it over alternatives ('PREFER this over reading GetInfo alone'). It also provides a concrete prerequisite: passing `height` when the daemon is unreachable, and recommends citing related_docs. This is exemplary usage guidance.

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