ioda-outages-mcp-server

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

Annotations only cover read-only/idempotent/open-world, and the description adds substantial non-obvious behavior: timeout risk on global searches, that source scores are not an absolute severity scale, boundary duplicate detections between adjacent windows, starts preceding 'from', ends clipped at 'until' with no recovery guarantee, and ignoreMethods filtering upstream before scoring. The includeAlerts size warning and 'keep filters and limit fixed' pagination rule are also 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?

Front-loaded with the purpose and window cap, and nearly every clause carries information that is not in the schema. It is, however, a dense semicolon-chained block with little visual structure, and a couple of clauses (zero-based pages, keep limit fixed) duplicate schema 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 12 parameters, an output schema, and annotations already in place, the description covers the remaining risk surface an agent needs before calling: timeout-prone configurations, window-span limits, default extension values, boundary duplication, and paging discipline. Nothing material is left undisclosed.

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 would be 3, but the description adds real semantics beyond the schema: the 14-day vs 1-day extendWindowSeconds default split by entityType, the 'a code requires its entityType' coupling, and the relatedToType/relatedToCode scoping semantics. Only the ignoreMethods exclusion grammar and the page/limit rules are essentially restated from 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 ('Find IODA outage events') plus the binding constraint ('overlapping an explicit Unix-second window of at most 31 days'), which is far more than a restatement of the name. It never names a sibling, though, so an agent must infer from the plot whether to use this versus ioda_summarize_outages or ioda_get_alerts.

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 concrete selection guidance: omit entity filters for global scope, and narrow the window or add entityType when global multi-day searches time out. It also states the entityCode-requires-entityType rule and the relatedToCode/relatedToType pairing. It does not explicitly route to the aggregate sibling (ioda_summarize_outages) or alerts sibling, which keeps it below 5.

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 only cover readOnly/openWorld/idempotent, yet the description adds substantial behavioral context: bounds widened by extendWindowSeconds, duplicate boundary detections across adjacent windows, upstream ignoreMethods filtering, the 100/14-day serving caps, and the caveat that missing transitions do not establish health. That is exactly the extra context annotations cannot supply.

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 purpose and window limits, and each subsequent sentence carries a real constraint or caveat. It is dense and long, but no sentence is redundant 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?

For an 11-parameter tool with an output schema, the description covers time-window semantics, pagination behavior, filter interactions, truncation notices and timeout risk, so an agent has everything needed 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%, so the baseline would be 3, but the description contributes cross-parameter constraints the schema documents only in isolation: a code requires entityType, relatedToType excludes entityCode, relatedTo* is served at page 0 only, and filters plus limit must stay fixed across pages.

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: retrieve IODA detection and recovery transitions within an explicit Unix-second window of at most 31 days. The scope is unambiguous, but the description never contrasts the tool with siblings like ioda_get_signals or ioda_find_outages, so the agent must infer which query surface to pick.

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 concrete usage conditions: omit entity filters for global scope, a code requires entityType, relatedToType/relatedToCode are limited to page 0, and it points at ioda_search_entities for name resolution. It stops short of naming when to prefer the sibling outage/signal tools instead.

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?

Goes well beyond the readOnly/idempotent annotations by disclosing interpretation-critical behavior: nulls mean missing observations rather than zero connectivity, maxPoints triggers upstream aggregation rather than first-N sampling so smaller values degrade temporal resolution, and returned buckets are aligned with exclusive bounds that may extend past the requested window. These are exactly the traits an agent cannot infer from structured fields.

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 core action and scope, then ordered into constraints, semantics, and return-shape caveats; every sentence carries information. Slight redundancy with the schema's maxPoints wording and dense noun-stacking keep it from a 5.

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, the description need not explain return values, yet it still explains boundary alignment and exclusive bounds, which is what an agent needs for cross-source comparison. What remains missing is sibling routing — nothing tells the agent when to prefer this over ioda_get_status or ioda_find_outages for the same entity.

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 the baseline is 3. The description does add interpretive value for maxPoints (aggregation vs. sampling trade-off) and the source enum, but much of that content duplicates the schema text verbatim, and it adds nothing for from/until/entityType/entityCode beyond what the schema already specifies.

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 (Fetch) and a precisely enumerated resource: numeric BGP visibility, ping-slash24 probing, or Merit telescope series for a single entity within an explicit Unix-second window capped at 31 days. The scope language ('one entity', 'explicit Unix-second window') makes it distinguishable from status/outage-summary siblings without opening any schema.

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 constraints are stated (source is required and limited to three values; window at most 31 days), which implies when the tool is applicable, but there is no explicit routing guidance against siblings such as ioda_get_status or ioda_find_outages. The only alternative-tool pointer ('resolve names with ioda_search_entities') lives in the entityCode schema description, not the tool description.

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 the safety profile (readOnly, idempotent, openWorld), but the description adds interpretive behavior that annotations cannot convey: partial failures surface explicitly, the 1800-second publication allowance makes buckets pending rather than missing, 'no alerts is not an all-clear,' and IODA measures macroscopic connectivity rather than a single office or shutdown cause. These caveats materially change how an agent should report results, which is exactly the value-add expected at this bar.

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 purpose is front-loaded in the first sentence and every subsequent sentence carries distinct information (evidence sources, failure behavior, status vocabulary, connectivity caveat). It is dense but not padded; terms like 'ping-slash24' and 'merit-nt' are opaque without domain familiarity, which is a minor readability cost.

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 composite aggregator with an output schema (which removes any need to describe return values), the description covers the status vocabulary, publication-lag semantics, partial-failure behavior, and interpretation limits. The remaining gap is routing guidance for degraded cases, which points at sibling tools but never names them.

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 schema already documents all three parameters, and the baseline of 3 applies. The description restates the 1–24 hour lookback and 'one entity' scope without adding format or syntax detail. It also slightly understates the schema's maximum of 240 while the schema explains the clamping-with-notice behavior, leaving the description marginally weaker than the structured field.

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: inspect IODA detection evidence and measurement coverage for one entity over a 1–24 hour lookback. The enumeration of collected evidence (events, alerts, bgp, ping-slash24, merit-nt) makes clear this is an aggregate status snapshot, which implicitly distinguishes it from ioda_get_alerts and ioda_get_signals. It stops short of naming any sibling explicitly, so full 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?

'Partial failures remain explicit and route to standalone tools' gestures at alternatives without naming them, so an agent cannot tell whether that means ioda_get_alerts, ioda_get_signals, or both. There is no guidance on when to prefer ioda_find_outages or ioda_summarize_outages over this aggregate view. Usage is implied by the framing ('inspect ... for one entity') 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?

The annotations already declare read-only, idempotent, open-world behavior. The description adds useful caveats beyond the annotations, including that metadata does not establish measurement coverage and that pagination is zero-based with a fixed limit when continuing.

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 front-loaded with purpose and then covers parameter modes, relationship scoping, and pagination caveats. It is dense but efficient; each clause adds actionable information, though the single long paragraph is less scannable than it could be.

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 seven-parameter search tool with full schema descriptions, annotations, and an output schema, the description covers the important modes, relationship scoping, code formats, and pagination behavior. No critical invocation detail appears to be missing.

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 the baseline is already strong. The description nevertheless adds semantic guidance about entityType values, mutual exclusivity of query and entityCode, code formats such as 40934-576 and 59962-IR, and how related scopes combine with query.

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: resolving country, region, ASN, and geoasn names and codes for outage investigations. It clearly distinguishes the entity types it handles, but it does not explicitly contrast itself with sibling tools such as ioda_find_outages or ioda_get_alerts.

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 explicit invocation guidance: choose entityType and either query or entityCode, omit both to list the type, and use relatedToType with relatedToCode to scope results. It does not explain when to use this tool instead of the sibling outage, alert, signal, status, or summary tools.

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 provide readOnly/idempotent/openWorld, and the description goes well beyond: it discloses score construction, that scores are window totals not current status, non-comparability across windows, boundary duplication from inclusive 'until', timeout risk, and that an empty result is not an all-clear.

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-loads purpose and ranking order, with zero filler. It is dense and crammed into a single paragraph, so structure could be improved, but nearly every sentence carries non-redundant 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?

For a 10-param read tool with a full output schema and complete param descriptions, the description covers the tricky edges an agent needs (window comparability, exclusions, pagination stability, timeouts, empty results). Nothing essential is missing.

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 nonetheless adds meaning beyond the schema, e.g. ignoreMethods exclusion semantics and cross-request consistency, and explains entityCode vs relatedToType/relatedToCode roles. Minor gaps like extendWindowSeconds are left largely to 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 (Rank), resource (entities of one entityType), metric (IODA outage summary score), and window constraint (at most 31 days), with a concrete example. Clearly distinguishable from siblings like ioda_find_outages or ioda_get_alerts.

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?

Explains when to use relatedToType/entityCode scoping, warns large type-only rankings can time out, and notes that rankings/drill-down calls should keep filters and exclusions fixed. It implies events and alerts as alternatives but never explicitly names a sibling to use instead.

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