NOMOS Cross-Border Broker

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

Annotations already cover readOnly, idempotent, non-destructive, so the description doesn't repeat those. It adds the context that no network requests are made and that the artifact updates once daily. Brief mention of return content is included, but still light on edge cases like freshness or failure behavior, so it earns a 3 rather than 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?

Two sentences, dense with accurate info. It front-loads the core value and then clarifies constraints. Slightly more context than strictly needed, but still 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?

For a read-only tool with three optional filtering params and an output schema, the description covers the essentials: what, when, and what it never does. Enough for an agent to invoke it effectively without over-explaining.

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 all three parameters have clear enums/descriptions and defaults. The description adds the crucial 'no live scanning' nuance, which complements, rather than repeats, 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 has a clear verb ('Returns...'), specifies the resource ('read-only view of the most recent local daily scan artifact'), and zooms in on the six regions covered. It also sets expectations by noting it's a local artifact, not live scanning.

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

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

It gives the key context: the artifact is written once a day by a separate job, so users know this is a bounded, cached view. It doesn't outline explicit when-not-to-use cases, but the daily-update note helps prevent misuse.

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 adds behavioral constraints beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false). It explicitly states 'Local lookup only — no network access, no legal advice,' which is critical operational context. It also discloses the full set of return fields and the ERROR case for unsupported input, providing transparent expectations without contradicting any annotation.

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

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

Two sentences, front-loaded with the core purpose, followed by the output summary and constraints. Every sentence provides essential information without redundancy. The structure is efficient and scannable, ideal for quick decision by an agent.

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 moderate complexity (3 required params, all enums, existing output schema), the description provides complete context: what it does, what it returns (including ERROR case), and its constraints (local lookup, no legal advice). The presence of the output schema means the description doesn't need to enumerate every return field, but it still highlights the key outputs. This is a complete and self-sufficient 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% with detailed parameter descriptions and enums for each of the three parameters. The description reinforces the 'jurisdiction pair' and 'data category' but does not add new semantic depth beyond what the schema already provides. This matches the baseline of 3 for well-covered 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 clear specific verb+resource: 'Cross-border regulatory preflight for agent data flows.' It explicitly states the checks (jurisdiction pair, data category) against a policy matrix and the output verdicts. This clearly distinguishes it from the sibling tools, which handle market scans, tool discovery, receipt verification, and X402 quoting — all different domains.

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 clearly indicates when this tool is used: for regulatory preflight of agent data flows between jurisdictions. It specifies the exact inputs (jurisdiction pair, data category) and the output (verdict, blocked_fields, etc.). While it doesn't explicitly mention when NOT to use it or name alternative tools, the distinct purpose makes the usage context evident. It could have added a sentence like 'Use this before any cross-border transfer to assess compliance' but the context is sufficient.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds valuable beyond-annotation context: it is local-only and will not contact any network endpoint. This meaningfully prevents misuse as a network scanner and clarifies the static nature of the catalog.

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, front-loaded with the action and search dimensions. The second sentence delivers output details and a safety-relevant constraint. No filler or redundant restatement of the tool name.

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 catalog-search tool with rich annotations and an output schema, this description covers purpose, search dimensions, result contents, and the key local-only/no-network behavior. There are no significant contextual 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%, with both 'query' and 'category' already described in the schema. The description only restates the filtering role of keyword and category without adding new semantic detail, syntax guidance, or edge-case behavior, so it stays at 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 uses a specific verb ('Search') and a specific resource ('small static curated catalog of OracleNet MCP tools'), and clearly states what it returns: tool names, endpoints, and protocol support. This distinguishes it from the sibling domain-specific tools, which are actual operations rather than catalog discovery.

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

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

The description provides clear context by stating this is a local, static catalog search and explicitly excludes probing, crawling, or network contact. It implies when to use this vs. operational sibling tools, though it does not explicitly name alternatives or state 'use X instead when you need to perform an actual operation.'

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, and destructiveHint=false. The description adds behavioral nuance beyond these: exact matching against stored fields, the optional 'sha256:' prefix, and the critical caveat that the response always reports cryptographically_verified: false. This prevents a major misunderstanding, though it doesn't cover all possible edge cases (e.g., not found 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 a tight three sentences: first states the action and target, second provides format and matching details, and third clarifies a likely misconception. No wasted words, all information is pertinent, and it is front-loaded with the key verb and object.

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 tool with robust annotations and an output schema, the description covers all necessary aspects: purpose, input format, matching behavior, and a warning about common confusion. There are no missing behaviors that an agent would need to know 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?

The schema covers the single parameter fully (100% coverage) with a description including the 64-hex requirement and optional prefix. The description reinforces the format and clarifies matching semantics ('matching is exact against the stored receipt_hash/entry_hash fields'). It adds a slight enhancement over the schema by linking the parameter to both hash fields, but the core semantics were already well-documented in 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 uses a specific verb+resource construction: 'Look up a NOMOS operation record by its exact SHA-256 receipt hash in the local handshake audit log.' It clearly differentiates from cryptographic verification, which is a likely point of confusion, and leaves no ambiguity about its scope (exact-match 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?

The description explicitly states when to use the tool (exact receipt hash lookup) and firmly excludes misuse ('NOT cryptographic signature verification'). While it doesn't name an alternative tool, the negative guidance plus the format requirement ('Requires a full 64-hex hash') gives clear usage context. A minor gap is the absence of a mention of an alternative tool for verification.

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 adds behavioral specifics beyond the annotations: it states no payment, signing, persistence, or reservation, and clarifies that the digest is not a signature. It also notes the expiry is informational only. This aligns with annotations (readOnly, idempotent) and provides valuable context, especially given the openWorldHint=false.

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 efficient, with each sentence carrying information: the purpose, tier pricing, and behavior. It is slightly longer than the ideal two-sentence version but remains well-structured and front-loaded with the core purpose. No fluff or redundant phrasing.

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, an output schema (not shown but present), and comprehensive annotations. The description covers behavior (stateless, unsigned), return fields (payTo, network, amount, digest), and constraints (expiry informational). It fully addresses the tool's complexity and adds value where needed.

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, but the description adds concrete cost details for the tier enum ($0.02, $0.05, $0.10), which the schema only describes qualitatively. This adds meaningful meaning beyond the schema, but the service parameter is not further elaborated. Baseline 3 is elevated due to the price addition.

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: 'Get a stateless, unsigned, informational x402 price quote for NOMOS services.' It specifies the verb (Get), resource (price quote), and scope (stateless, unsigned, informational). It also lists the tiers and return elements, making it distinct from sibling tools that perform actual operations.

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 conveys when to use the tool (before payment, for informational quotes) and explicitly states what it does NOT do ('No payment is initiated and nothing is signed, persisted or reserved'). However, it does not explicitly contrast with sibling tools or mention when to avoid it, though the context makes it clear.

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