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

With no annotations, the description carries full burden. It explicitly discloses that this is a read operation (get) and specifies the exact return fields (service_name, service_version, spec_version). No destructive behavior is 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 three sentences long: first sentence states the core purpose, second provides a use case, third lists return values. Every sentence adds value with no redundancy 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?

Given zero parameters and an output schema present, the description provides sufficient context: what the tool does, why to use it, and what it returns. It is complete for a version info tool without missing details.

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 are no parameters, so schema coverage is 100%. The description does not need to cover param semantics, but it adds value by detailing the output fields, which helps the agent understand what the tool returns without needing the output 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 'Get iota-mcp service version and upstream programme data version', specifying the exact resources and operation. It distinguishes itself from sibling tools like iota_dxcc or iota_search by focusing on version information.

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 a clear use case: 'confirm fleet alignment across MCP deployments'. It explains when to use (to detect drift) but lacks explicit guidance on when not to use or alternatives, though the sibling tools cover different IOTA functions.

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?

Without annotations, the description carries the burden of behavioral disclosure. It explains the bidirectional nature and conditional usage, but does not specify behavior when both parameters are provided, when none are provided, or any side effects, authentication requirements, or rate limits.

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 only two sentences, front-loaded with the core purpose. Every sentence adds value with no redundancy or waste. It is appropriately concise.

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 existence of an output schema, the description does not need to detail return values. It adequately covers the two modes of operation. However, it lacks guidance on handling invalid inputs (e.g., both parameters provided or none), which slightly reduces completeness.

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 already has 100% description coverage with examples. The tool description adds functional meaning by clarifying the direction of mapping for each parameter ('find all IOTA groups for a DXCC entity' vs 'find which DXCC entities an IOTA group belongs to'), which goes beyond the schema's brief 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?

The description clearly states the tool's purpose: bidirectional mapping between DXCC entities and IOTA groups. It specifies two distinct use cases (dxcc_num or refno) and uses a specific verb (mapping) that distinguishes it from sibling tools like general lookup or search.

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

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

The description provides clear usage conditions: use dxcc_num to find IOTA groups or refno to find DXCC entities. It implies the tool should be used when such bidirectional mapping is needed, though it does not explicitly mention when not to use it or compare with 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?

No annotations are provided, so the description carries full burden. It indicates a read operation (list) and explains the return structure (hierarchy), but does not disclose error handling, rate limits, or any side effects. Minimal disclosure beyond the core function.

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 two sentences, no wasted words, and directly states the purpose and output structure. It is front-loaded and efficiently communicates the key 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?

Given the presence of an output schema (indicated by context signals), the description explains the returned hierarchy adequately. It could be slightly more complete by defining an IOTA group, but for a simple list tool it is 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?

The input schema has 100% coverage with a clear description for the refno parameter. The tool description does not add additional parameter semantics beyond the schema, 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?

The description clearly states the tool lists all islands and subgroups in an IOTA group, with a specific verb (list) and resource (islands and subgroups). It distinguishes itself from sibling tools like iota_search or iota_lookup by focusing on the full hierarchy of a single group.

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 usage when needing a complete hierarchy of a specific IOTA group, but does not explicitly state when to use this tool over alternatives like iota_search or iota_lookup, nor does it mention any prerequisites or 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?

No annotations provided, so description carries full burden. It discloses that the tool is a read operation and lists return fields, providing adequate transparency for a lookup. Missing error handling details but acceptable.

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 waste. The first sentence states the action, the second lists return fields. Efficient and front-loaded.

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

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

Given the presence of an output schema and the simple nature of a lookup, the description is complete. It tells what it does and what it returns. No need for further detail.

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% (refno described with examples). The tool description adds no extra parameter detail beyond restating 'reference number', 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?

The description 'Look up an IOTA group by reference number' uses a specific verb and resource, clearly differentiating it from siblings like iota_search or iota_nearby.

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 usage when a reference number is available, but lacks explicit when-not or alternative guidance. However, the context is clear for a direct lookup.

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 the algorithm (great-circle distance, bounding box center) but lacks other behavioral traits such as authentication needs, data freshness, or any side effects. With no annotations, the description partially fulfills the transparency 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 only two sentences, front-loading the main action. Every word serves a purpose, with no repetition or unnecessary 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?

Given the tool's simplicity and the presence of an output schema, the description adequately covers the key aspects: what it does and how it computes results. It could optionally mention what constitutes an IOTA group, but this is not critical.

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 provides descriptions for all parameters (100% coverage). The tool description adds value by explaining how coordinates and limit are used in the distance calculation, which helps the agent understand parameter purpose 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 tool finds IOTA groups nearest to a location and explains the great-circle distance computation. It distinguishes from siblings by focusing on geospatial proximity, which is unique among the listed sibling 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?

No guidance is provided on when to use this tool versus alternatives like iota_search or iota_lookup. The description does not mention prerequisites, limitations, or scenarios where this tool is appropriate.

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 that it searches both groups and islands and deduplicates by reference number. With no annotations, it lacks details on read-only nature, rate limits, or 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?

Three concise sentences, each adding value: purpose, scope, and deduplication. 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 output schema present, return values are covered, but lacks context on when to search vs. other operations. Could mention that it is a simple name-based search.

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 both parameters with descriptions; description adds no additional meaning beyond what schema provides, 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?

Description clearly states it searches IOTA groups and islands by name, including both group and island names. However, it does not explicitly differentiate from sibling tools like iota_lookup or iota_nearby, leaving some ambiguity.

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?

No guidance on when to use this tool versus alternatives (e.g., iota_lookup for specific reference numbers). No mention of prerequisites or 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?

With no annotations, the description carries full burden. It describes returns but does not state side effects or safety (e.g., read-only). Assumes no destructive behavior but should explicitly confirm.

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?

Mostly concise, with a clear summary and specifics. Minor redundancy in the last line ('Returns: Programme-wide statistics and summaries') repeats earlier 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 inputs and presence of output schema, description adequately covers what the tool does. Could mention that no arguments are needed, but overall sufficient for a simple stats 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 schema coverage is 100%. Description adds value by detailing the output structure, compensating for the lack of parameter info (baseline 4 for 0 params).

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 it returns summary statistics for the IOTA programme, listing specific breakdowns (total groups/islands, continent, DXCC count, credited groups). This differentiates it from sibling tools that focus on specific islands or searches.

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?

Lacks explicit guidance on when to use vs alternatives, but the purpose is self-evident given the tool name and description. No exclusionary context is provided.

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