inam-mcp

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

Annotations already establish read-only, idempotent, non-destructive, open-world behavior, and the description adds substantial operational detail: the public signals checked, fallback behavior when INAM has no data, the verdict/checks return structure, and a 10-minute cache. There is no contradiction with 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 dense and front-loaded, starting with what is checked and then listing signals and return fields. Every clause contributes useful information, though the long run-on sentence could be easier to scan.

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 pre-payment verification tool with no output schema, the description covers the signals checked, fallback behavior, return fields, and caching. That is enough for an agent to understand what it does and how to interpret the result.

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 both the target and method parameters are already documented in the schema, including the enum values. The description restates the accepted target types but does not add method-specific guidance beyond what the schema provides, so baseline 3 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?

It uses a specific verb ('Checks') and enumerates exact target resources: an x402 endpoint URL, an EVM wallet, or a did:key, specifically before paying. The phrase 'Works when INAM has no data on the target' helps distinguish it from narrower reputation-only siblings, though no sibling is named explicitly.

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

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

The description gives a clear usage context: run it before paying a target. It also says it works even when INAM has no data, which is useful for selecting it over a data-dependent sibling, but it does not state explicit exclusions or name an alternative 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 readOnly/idempotent/closed-world, so the safety profile is covered; the description goes further by defining the evidenceLevel tiers in behavioral terms (receipts signed by both parties vs. operator-authorized verifier) and enumerating what each flag means. It does not cover not-found/unknown-DID behavior, which is the remaining gap.

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

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

Purpose is front-loaded in the first clause, then the return-field semantics follow in a compact block. Dense but every clause carries interpretive value since there is no output schema; minor cost that the tier definitions are packed into one long sentence.

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 and one trivial param, the description correctly carries the burden of explaining return values — trustScore, components, evidenceLevel tiers, and flags — which is exactly what an agent needs to interpret results. Missing only failure/empty-result behavior.

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 defines agentId; the description only restates that it is a did:key id with no additional format or validation detail. Baseline 3 is appropriate when the schema does the work.

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

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

States a specific verb ('looks up'), resource ('INAM reputation'), and keying ('by did:key id'), which is enough to separate it from the receipt/verify/hash siblings. It stops short of naming the nearest sibling (inam_check / inam_search_agents) to explain the boundary.

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?

There is no explicit when-to-use, when-not-to-use, or alternative routing statement; the agent must infer from the name that this is the pre-transaction reputation lookup rather than a raw check or search. The description spends its space on output semantics instead of invocation 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful domain context about what a receipt is (worker-signed, requester-countersigned when finalized) and what verification records represent, though it does not cover error behavior or authorization requirements.

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 two sentences, front-loaded with the action and resource, and the second sentence earns its place by defining the domain objects returned. There is no redundant or filler text.

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 one-parameter read tool with rich annotations and full schema coverage, the description explains the returned entities conceptually. It does not describe response structure or not-found behavior, and there is no output schema, but the core context is 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?

Schema description coverage is 100%, and the single receiptId parameter is documented in the schema as a "sha256:... receipt id." The description only says "by id" and adds no format or syntax detail beyond the schema, so the baseline of 3 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 states a specific verb and resource: "Fetches a single execution receipt by id together with its verification records." It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as inam_verify_receipt or inam_search_agents.

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

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

The description implies retrieval by receipt id but gives no explicit when-to-use guidance, no exclusions, and no named alternatives. An agent must infer that this is the lookup tool when a receipt id is already known.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral facts: hashing is performed locally and is deterministic/reproducible by anyone with the same text, which tells the agent no network call or secret is involved.

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 with the output format front-loaded and no filler; every clause carries information about what is produced or how it behaves.

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 pure function with no output schema, the description supplies the return format, the determinism guarantee, and the domain meaning of the hash, leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is 100% and the single parameter is already documented as 'the exact spec or output text to hash'. The description reinforces the 'exact text' requirement but adds no format or encoding details beyond the schema, so baseline 3 applies.

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

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

States a specific verb (computes) and resource (sha256 content hash) and pins the exact output format 'sha256:<64 hex>'. It also ties the result to INAM's specHash/outputHash fields, which no sibling tool does, so an agent can distinguish it immediately.

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 gives clear context for when this tool is relevant, and no sibling offers hashing so there is no alternative to route away from. It stops short of explicitly saying when not to use it or what to do with the resulting hash.

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, so the safety profile is covered. The description adds genuinely new behavior: revoked agents and self-declared demo agents are excluded from results, plus a summary of the returned record shape. No pagination, result-count limits, or empty-result behavior is disclosed.

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; the core operation and filter dimensions come first and the exclusion rules and return shape follow in a compact clause.

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 2-parameter, optional-both search tool with no output schema, the description covers purpose, filters, exclusions, and return fields — enough to call it correctly. Only result-size/pagination behavior is unaddressed, a minor gap at 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?

Schema coverage is 100% and both parameters already carry descriptions with an example capability string, so the baseline is 3. The description restates the two filters but adds no syntax guidance (e.g., matching semantics for capability, scale or range of trust score) 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 (Searches) plus resource (INAM-registered agents) and the two filter dimensions (capability, minimum trust score), then lists the returned fields. Sibling tools (inam_check, inam_get_receipt, inam_hash_content) are clearly different functions, though no sibling is named explicitly.

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 — discovery of agents by capability and/or trust threshold — but there is no explicit statement of when to use this versus inam_check or inam_check_reputation (e.g., search first, then verify a specific agent). 'and/or' signals both parameters are optional but that is already in 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, idempotentHint, and destructiveHint=false, so safety is covered; the description adds substantial context beyond that with the exact per-check list, the pre-v0.32 placeholder-hash failure mode, and the skipped-hash behavior when spec/output is omitted. It does not discuss rate limits, auth requirements, or costs of the hosted attestation, which keeps it at adequate rather than exceptional for an annotated tool.

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

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

Front-loaded with the action and return verdict, followed by the check enumeration and the two caveats about non-execution and reputation. It is dense but every clause carries information; the check list is long, though each named check is load-bearing.

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 exists, so the description carries the full burden of describing returns, and it does: verdict, per-check results, inclusion proof, net verdict of independent verifications, next step, and an Ed25519 attestation. An agent has everything needed to call it and interpret the response.

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 real meaning beyond the schema by explaining that spec_hash and output_hash checks are 'skipped' unless the optional spec and output text are supplied. That is genuine semantic guidance about parameter interaction that the schema does not state.

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: runs the registry's integrity checks on one receipt and returns a pass/fail verdict. It also draws an explicit boundary the siblings don't cover, noting this is not an independent verification and is not counted toward reputation, so an agent can tell it apart from inam_check or inam_check_reputation.

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?

Implies usage clearly via the caveat that work is not re-executed and the result is not recorded or reputation-counted, which tells the agent when this lightweight check is appropriate versus a heavier verification path. It never names an alternative sibling tool, so routing is inferred rather than explicit.

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