inam-mcp

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

Annotations already cover safety (readOnly, idempotent, openWorld, non-destructive), so the description's value-add is the caching window ('cached for 10 minutes') and the graceful-degradation note that it still works without INAM data. It also discloses what third-party signals are consulted (402 requirements, ERC-8004, Web Bot Auth, domain age), which the annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded in the opening clause, followed by data sources and then return shape. It is dense but the clauses are informative rather than redundant; the return-field enumeration could be trimmed slightly given the readOnly/idempotent profile.

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 present, the description carries the return-value burden and discharges it fully (verdict, checks[] with status/label/detail, payment, next, cachedAt). It also covers the fallback path and caching, leaving no obvious gap for a 2-parameter read 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%, so both parameters are already documented, and the description duplicates the target-type list without adding syntax or format detail. The 'method' parameter and its POST caveat are never echoed in the description, so no value is added 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?

States a specific verb (check) and enumerates the accepted target resources (x402 URL, EVM wallet, did:key) plus the operative context 'before paying it'. An agent can tell this apart from inam_check_reputation or inam_verify_receipt because it is framed as a consolidated pre-payment gate, not a single-signal lookup.

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?

'before paying it' gives a clear trigger condition, and 'Works when INAM has no data on the target' sets expectations for a weak-signal case. However, it never names a sibling as the alternative (e.g., when to prefer inam_check_reputation directly), so there are no explicit exclusions.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description earns credit by going well beyond that: it defines the three evidenceLevel states and enumerates the flag semantics (attestation_rejected, in_dispute, revoked, concentrated_counterparty, etc.), which is meaningful behavioral context. It omits however anything about auth, rate limits, or failure 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?

A single front-loaded sentence establishes the operation before the dense return-value enumeration. The output detail is lengthy but justified given there is no output schema; little is redundant.

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 carries the full burden of explaining return values and does so thoroughly (score fields, evidence levels, flag vocabulary). For a simple one-parameter read it is essentially complete; only usage guidance is absent.

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

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

Single parameter at 100% schema coverage, so the schema already documents agentId with its did:key format. The description's 'by did:key id' phrasing restates rather than extends that; baseline 3 applies.

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

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

States a specific verb ('looks up') and resource ('an agent's INAM reputation') plus the keying parameter ('by did:key id'), so the operation is unambiguous. It does not, however, distinguish itself from nearby siblings such as inam_check or inam_search_agents, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description never says when to reach for this tool versus alternatives (e.g., inam_check or inam_search_agents), nor does it state prerequisites or exclusions. All of the text is about output semantics, leaving usage entirely to inference.

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, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description earns credit by explaining domain semantics the annotations cannot: that a receipt is a worker-signed job record later countersigned by the requester, and that verification records are verdicts from operator-authorized verifiers.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences: the operation is front-loaded, and the second sentence supplies only the domain gloss needed to interpret the return payload. 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?

With no output schema, the description must explain what comes back, and it does — a receipt plus its verification records, with definitions of each. It stops short of stating error behavior (e.g. not-found or unfinalized receipts) or auth prerequisites, which would round out a single-parameter read 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?

There is a single parameter and schema description coverage is 100%, so the schema already documents receiptId as a 'sha256:...' id. The description only restates 'by id' and adds no format, validation, or error nuance beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb (fetches) and resource (a single execution receipt by id) and even previews the returned payload (its verification records). It is clear what the tool does, but it never names or contrasts with the closely related sibling inam_verify_receipt, so sibling differentiation is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by 'fetches a single execution receipt by id' — a read-one-by-identifier operation — but there is no explicit when-to-use, when-not, or pointer to alternatives such as inam_verify_receipt or a search tool. The guidance is adequate but leaves the agent to infer routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world. The description adds genuinely new behavior beyond that: hashing is performed locally with no external call, and the hash is deterministic/recomputable by any holder of the same text. It does not discuss error cases (e.g. empty input), but adds real context over the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, front-loaded with the concrete result format before the explanatory property. Every clause earns its place.

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

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

For a single-input, no-output-schema, annotation-covered utility, this is complete: the 'sha256:<64 hex>' string in the description substitutes for the missing output schema, and the local/deterministic note closes the remaining behavioral gap.

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?

One parameter with 100% schema description coverage ('the exact spec or output text to hash'), so the schema already carries the semantics. The description adds only 'the given text' and the note about exactness of the output format, which is marginal 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?

States a specific verb and resource ('Computes the ... content hash of the given text') and pins down the exact output format ('sha256:<64 hex>') plus its role in INAM (specHash/outputHash). No sibling tool (search, receipts, reputation, whoami) does anything similar, so the agent can route unambiguously.

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 mention of specHash and outputHash implies the hash is meant to feed receipt verification, but the description never states when to call this versus the verify/check siblings, and gives no preconditions or exclusions. Usage is inferable rather than stated.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so safety is covered. The description adds genuinely new behavior: revoked agents and self-declared demo agents are excluded from results, which an agent could not learn from the annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, with the purpose and filter scope front-loaded and the result/exclusion detail following. Every clause carries information.

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 helpfully enumerates the returned fields (did:key id, capabilities, metadata) and the exclusion rules, which is enough to call it correctly. It omits result-set size, pagination, or empty-match behavior, which is a minor gap for a search 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%, so both parameters are already documented, and the description only restates the capability/trust-score filter axes without adding format or semantics beyond the schema examples. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource (searches INAM-registered agents) and the two filter axes (declared capability, minimum trust score). It also names the returned fields and the exclusions, which clearly separates it from sibling tools like inam_check_reputation or inam_check that operate on different resources.

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 'and/or' phrasing implies both filters are optional and composable, so an agent can infer usage. However, it never says when to prefer this over inam_check_reputation (which presumably checks a single agent's score) or names any alternative, leaving routing to inference.

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

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

With annotations already covering readOnly/idempotent/non-destructive, the description adds substantial value: it enumerates each check performed, discloses conditional behavior (spec_hash/output_hash 'skipped' unless text is supplied), explains the pre-v0.32 placeholder-hash failure mode, and notes the returned Ed25519 attestation. It also explicitly disclaims that work is re-executed or that reputation is affected.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and verdict format are front-loaded, and each subsequent clause covers a distinct behavior worth knowing. The second and third sentences are dense and run-on with parentheticals, costing some readability, but there is little outright 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?

There is no output schema, so the description carries the return-value burden and does so thoroughly: per-check names, verdict semantics, inclusion proof, attestation, and a next-step hint. Combined with the explicit non-independence disclaimer, an agent has everything needed to interpret and trust the result appropriately.

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, but the description adds semantics the schema lacks: spec and output are used to compare against task.specHash and result.outputHash, and omitting them yields 'skipped' rather than a failure. That conditional outcome is genuinely useful and not derivable from 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 opening sentence names a specific verb and resource ('Runs the registry's integrity checks on one receipt') and states the return shape ('verdict (pass or fail) with per-check results'). It is clearly distinguishable from siblings like inam_get_receipt or inam_check because it enumerates the integrity checks it performs.

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 closing sentence establishes an important boundary: 'The work is not re-executed: this is not an independent verification and is not recorded or counted toward reputation.' That tells the agent when this tool is the right (registry-side, non-authoritative) check. It stops short of naming the specific alternative tool an agent should use for independent verification.

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