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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds genuine context beyond that: the operation is a lightweight, MCP-protocol-internal check suitable for cross-server drift comparison, which tells an agent it needs no external IOTA API round-trip.

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, and the second paragraph gives the operational rationale. There is mild redundancy between 'iota-mcp service version and upstream programme data version' and the restatement as 'running PyPI version ... and IOTA programme data revision in use', but nothing wasteful overall.

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 no-parameter, read-only version probe with full annotations and an output schema, the description supplies everything needed: what is returned, why an agent would call it, and that it stays within the MCP protocol.

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?

Zero-parameter tool with 100% schema coverage, so the baseline is 4. The description usefully identifies the two outputs (service_version, spec_version) even though the output schema already documents them.

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 ('Get iota-mcp service version and upstream programme data version') and names the two returned fields, which no sibling tool (iota_lookup, iota_search, etc.) offers. An agent can immediately separate this diagnostics call from the data-lookup siblings.

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?

Gives a concrete use case: confirm fleet alignment across MCP deployments and compare service_version/spec_version to detect drift. It does not explicitly exclude scenarios or name an alternative tool, but for a zero-argument diagnostic the context is clear enough to select it correctly.

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 read-only, idempotent, non-destructive, open-world behavior. The description adds useful behavioral context by tying each parameter to a different result direction, though it does not clarify precedence when both or neither parameters are supplied.

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 front-load the bidirectional mapping purpose and then explain parameter selection. 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?

With annotations, full schema coverage, and an output schema, the description is nearly complete for invocation. The only notable gap is that it does not specify behavior when both parameters are provided or when neither is provided.

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 meaning beyond the schema by stating what each parameter returns: all IOTA groups for dxcc_num, or DXCC entities for refno. Examples and format details remain 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 states a specific resource and operation: bidirectional DXCC-to-IOTA mapping. It clearly explains both directions of the mapping, which distinguishes it from generic sibling lookup/search 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?

It explicitly tells the agent which parameter to provide for each lookup direction: dxcc_num for DXCC-to-IOTA, refno for IOTA-to-DXCC. It does not name sibling alternatives or exclusions, but the primary usage path is 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?

Annotations already declare readOnly, idempotent, non-destructive and open-world behavior, so safety is covered. The description adds that results come back as a nested hierarchy (subgroups containing islands), which is useful shape information, but says nothing about depth, ordering, or empty results.

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 short sentences, front-loaded with the action and scope, with no wasted filler. The second sentence is mildly redundant with the first but does add the nesting 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 annotations covering the safety profile and an output schema present, the description needn't explain return values. What it provides—action, scope, and hierarchy shape—is sufficient for an agent to call this correctly; only the relationship to sibling lookup tools is left implicit.

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 with 100% schema description coverage, and the description adds no further meaning about the refno format or constraints beyond what the schema provides. Baseline 3 for full schema coverage with no added parameter context.

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 names a specific verb (List) and resource (islands and subgroups in an IOTA group) and clarifies the returned structure as a hierarchy. It is clearly distinguishable from siblings like iota_lookup or iota_stats, though it does not explicitly name those alternatives to sharpen the distinction.

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 only implied: an agent can infer you call this when you need the island/subgroup breakdown for a group identified by refno. There is no explicit statement of when to prefer this over iota_lookup or iota_search, and no exclusions or prerequisites.

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, openWorld and non-destructive, so the safety profile is covered. The description's field list ('name, DXCC entity, bounding box, center coordinates...') largely duplicates what the existing output schema conveys, and it says nothing about error behavior for an invalid or nonexistent reference number.

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 short sentences, front-loaded with the action and the key. The enumerated return fields are somewhat redundant given the output schema, which is the only minor waste.

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 exact lookup with a full annotation set and an output schema, the description covers action, key, and result shape adequately. The remaining gap is routing guidance relative to iota_search, which would be the main thing missing for an agent choosing between siblings.

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 'refno' parameter already carries a format example (NA-005, EU-005, AF-001). The description adds no format, casing, or validation detail 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?

States a specific verb+resource combination: look up an IOTA group by reference number, and the 'by reference number' qualifier implicitly separates it from the sibling iota_search. It stops short of naming iota_search explicitly, so the differentiation is inferred rather than stated.

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 only implied: 'by reference number' signals an exact-key lookup, which contrasts with iota_search, and the presence of iota_nearby/iota_islands suggests other access paths. No sentence states when to prefer this tool or what to do if the refno is unknown.

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, openWorld, and non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral detail by disclosing the algorithm — great-circle distance to each group's bounding-box center — which tells the agent results are approximations, not exact polygon distances. It stops short of stating result ordering, which matters for interpreting `limit`.

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 short sentences: the purpose is front-loaded and the second sentence exists solely to explain the distance computation, which directly affects how results should be read. No filler, no repetition of schema or annotation 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?

With an output schema present, return values need no explanation, and annotations cover the safety profile. The only material omission is whether results are sorted by distance and what happens when fewer than `limit` groups exist — useful for a proximity tool but not required to invoke 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 description coverage is 100%, so latitude, longitude, and limit are already fully documented with units and an example. The description's "given coordinates" merely restates the schema; baseline 3 applies when the schema carries parameter 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?

States a specific verb and resource ("Find IOTA groups") plus a qualifying scope ("nearest to a location"), which clearly separates it from lookup/search/islands siblings that are name- or criteria-based. It does not explicitly name an alternative, so the differentiation is implicit rather than stated.

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 only implied: an agent infers it should call this when it has coordinates and wants proximity-ranked IOTA groups. There is no explicit when-to-use/when-not guidance and no mention of the sibling tools (iota_search, iota_lookup) as alternatives for non-geographic queries.

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, open-world, and non-destructive behavior. The description adds useful behavioral context beyond that: it searches across both group and island names and deduplicates results by IOTA reference number, which helps an agent interpret the result set.

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 short sentences with no filler. The core purpose is front-loaded, and the deduplication detail is a compact, useful follow-up.

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, the schema is fully documented, annotations are rich, and an output schema exists. The description covers the key domain behavior and result deduplication, though it omits ranking/ordering details that could help interpret search results.

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 goes beyond the schema examples by explaining that the query is matched against both group names and individual island names, which clarifies the semantics of the query 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?

States a specific verb and resource ('Search IOTA groups and islands') and clarifies the search domain (group names and individual island names). It distinguishes itself implicitly from reference-based lookup siblings, but does not explicitly name an alternative 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?

The phrase 'by name' and the note that both group and island names are searched imply the appropriate use case. However, there is no explicit when-to-use guidance, no exclusions, and no named sibling alternative such as iota_lookup for reference-based retrieval.

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, openWorldHint and destructiveHint=false, so safety and reproducibility are covered. The description adds value by disclosing the actual content of the payload (totals, continent breakdown, DXCC count, most/least credited groups), but says nothing about data provenance, freshness, or cost of the open-world call.

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 purpose and followed by a compact enumeration of return categories. No filler, no 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?

A no-parameter tool with an output schema and full annotation coverage needs little, and the description supplies the only missing piece — the shape of the summary. Minor gap: no note on what population or version of the IOTA programme the statistics reflect.

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?

Zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate and it correctly makes no parameter claims.

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?

Specific verb ('Get') plus a clearly scoped resource ('IOTA programme summary statistics'), with the returned fields enumerated. It is obviously distinct from the sibling tools (iota_lookup, iota_search, iota_nearby) which all target individual records rather than aggregate counts, though it never names them 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 only implied: the word 'summary' signals this is for aggregate/overview needs rather than per-record queries, but there is no explicit statement of when to prefer it over iota_search or iota_islands, and no prerequisites or exclusions are given.

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