PeppolStatus

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

With readOnlyHint=true already indicating a safe read, the description adds valuable behavioral context beyond annotations: it explains that stale keys resolve to the current Provider and that the returned key is always canonical. It does not cover error handling or rate limits, but the stale-key behavior is a meaningful disclosure.

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 the core purpose and then provides dense but relevant detail about the return payload. It avoids fluff, though the single long paragraph could be better structured with line breaks for readability; every sentence contributes 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 no output schema, the description thoroughly describes the returned fields (display name, verified flag, member seats, roster size, country composition, software grouping, hostname counts) and explains the stale-key resolution. For a single-parameter read tool, this is complete enough for an agent to know what to expect.

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 key parameter is already documented in the schema. The description adds semantics by clarifying that stale keys are accepted and resolve to the current Provider, and that the returned key is canonical, which goes beyond the schema's simple example-based description.

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 a specific verb and resource: 'Get an access point' and then defines it as 'One Provider's detail', listing the returned data. It does not differentiate this tool from close siblings like get_provider or get_public_provider, so it is clear but lacks sibling discrimination.

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 guidance on when to use this tool versus alternatives such as get_provider or list_access_points. The only usage-like detail is the stale key resolution behavior, which is a special case rather than a general when-to-use statement.

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 goes well beyond the readOnlyHint annotation by explaining the data semantics: definitions of joiners (with a data-availability caveat for 2026-08-02 onward), movers, and leavers, as well as the period defaulting to trailing 30 days. This is substantive behavioral context that is not evident from the annotations or schema.

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 well-structured and front-loaded: the first line states the core purpose, then each sentence adds necessary clarification about definitions and defaults. No redundant information is present, and the length is appropriate for the complexity of the subject.

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?

Despite the absence of an output schema, the description sufficiently describes the return contents: a daily category series, net growth, period totals, and the 'won from / lost to' breakdown. It also covers data definitions and default periods, making the tool's behavior and return value understandable without further documentation.

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 descriptions for all three parameters (key, from, to). The description adds context like 'Defaults to the trailing 30 days,' but this is largely already captured in the schema defaults. The description does not introduce new parameter syntax or format details, so a baseline score 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 clearly states the tool's purpose with a specific verb and resource: "Get an access point's churn." It then elaborates on what churn means (joiner/mover/leaver activity) and distinguishes it from sibling tools like get_access_point and get_country_churn by focusing on the access point's churn-specific data.

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 for when to use the tool (to retrieve churn data for a specific access point) but does not explicitly exclude alternatives or reference sibling tools like get_country_churn. It lacks explicit when-to-use/not-to-use guidance, but the specificity makes the intended usage 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?

Beyond the readOnlyHint annotation, the description discloses the internal 10,000-participant cap, the `degraded: true` response with null mixes, the guarantee of never returning a wrong number or an error, and the sparse-count behavior with un-enriched remainder derivation. This is exactly the kind of behavioral context an agent needs and the annotation alone does not provide.

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 lead sentence states the purpose, and the following paragraphs are tightly organized around capability, bounded behavior, and data semantics. Every sentence adds distinct value, and the 'BOUNDED BY DESIGN' section front-loads the most decision-critical behavioral constraint.

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 tool with no output schema, the description covers the five breakdowns, degraded mode, null mix behavior, participant_count relationship, sparse enrichment, and fallback strategy. An agent has enough context to call the tool, interpret degraded outcomes, and know what the returned mixes represent.

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 already covers 100% of parameters with detailed descriptions, so the baseline is 3. The description adds useful conceptual semantics: filters share names and shapes with `GET /v1/participants`, are scoped to the provider's seats, and lists parameter families that this endpoint cannot express. That elevates it above 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 opens with a specific verb and resource ('Get a filtered access point roster breakdown') and immediately pins down scope: five roster breakdowns recomputed over a filtered slice. It contrasts this with the stored whole-roster mixes on `GET /v1/aps/{key}`, so an agent can distinguish it from get_access_point and similar siblings without opening schemas.

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 clear context for when the filtered breakdown is useful ('so a breakdown stays true while the roster is cut down') and explicitly names `GET /v1/aps/{key}` as the fallback for stored whole-roster mixes. It also lists filters the endpoint cannot express, which helps callers decide whether this tool is appropriate. It stops short of an explicit when-to-use versus sibling-tool statement, but the guidance is strong.

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 provide readOnlyHint=true, so the description carries the burden of explaining behavior. It discloses suppression rules (numerators below 10 suppressed, denominators never), caching (cached for a day with monthly data moves), and the structure of the response. This goes well beyond the minimal read-only hint and provides actionable transparency.

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 longer than average but front-loaded with the core purpose and then layered with dense, useful detail about cuts, codes, suppression, and caching. Each sentence adds value, though some phrasing is complex and could be tightened without losing info.

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, the description must explain return values, and it does so thoroughly: list of headline fields, cuts and cross-tabs, coding schemes, suppression behavior, and caching. It also clarifies the data's geographic scope and update frequency. For a complex aggregate tool, this is complete.

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 country parameter is already described with an enum and explanation. The description adds no detail about the parameter beyond its role as the country selector; it does mention 'one country' but that is already evident from the schema. 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 begins with a clear verb+resource: 'Get a country's adoption aggregates'. It enumerates the exact content: headline totals, cuts, cross-tabs, and trend, making the tool's purpose concrete and distinct from sibling tools like get_country_churn or get_summary.

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 context is implied: this targets a single country's adoption aggregates, and the required 'country' parameter enforces that scope. However, the description does not explicitly mention when not to use it or name alternative tools (e.g., for multi-country or network-wide adoption), so the guidance is only implied.

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 readOnlyHint annotation already indicates a safe read operation, and the description's 'Get' is consistent with that. The description adds little behavioral context beyond what annotations provide, but there is no contradiction.

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 tool's purpose, and contains no unnecessary words or repetitive 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 simple read-by-id tool with one parameter, a readOnlyHint, and no output schema, this description is complete. It conveys the essential purpose and the key concept without needing extra 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?

The schema fully documents the 'id' parameter as 'The stable anomaly key.' The description adds 'content-derived' to clarify the key's origin, but this is a minor addition given the schema's already high coverage.

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 action ('Get an anomaly') and resource ('anomaly'), and specifies it retrieves a single anomaly by its stable content-derived key. This distinguishes it from sibling list_anomalies and other get_* 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?

The description implies usage when you have a known stable key for a specific anomaly, but it does not explicitly mention alternatives like list_anomalies for browsing or searching. The guidance is implied rather than explicit.

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, so the description does not need to restate safety. It adds valuable behavioral context beyond the annotation: data is read from pre-computed rollup tables, edge-cached, keyless-cacheable, and contains only aggregate counts with no participant/seat/hostname identifiers. These details help an agent understand latency, freshness, and privacy characteristics.

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 longer than necessary and contains nonessential noise such as GitHub issue references (#692, #716) and the awkward 'The free compliance landscape' phrasing. However, the core information is front-loaded in the first paragraph, and the country-scope explanation is substantive rather than padding. It is verbose but still scannable.

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-optional-parameter read-only tool with no output schema, the description is remarkably complete. It explains the returned aggregate shape, the no-identifying-data guarantee, the country-scoping behavior, and the cache/rollup origin. An agent has enough information to decide whether to use this tool, pass a country, and correctly 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?

The schema already describes the sole parameter with 100% coverage, so the baseline is 3. The description adds meaningful value by explaining how passing country changes the entire response body, that share percentages are relative to that country's open findings, and that the country code is echoed back. The AU/NZ example further clarifies interpretation of scoped results.

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 identifies a specific verb and resource: it returns the compliance landscape with per-country error rates and per-rule breakdowns. It also distinguishes itself from sibling tools by explicitly stating it returns counts only and that participant-level records are served by GET /v1/compliance/findings (Network tier). The odd phrase 'The free compliance landscape' is a minor distraction, but the core purpose is unambiguous.

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 clear usage guidance: if an agent needs participant, seat, or hostname records, it must use GET /v1/compliance/findings instead. It also explains when and why to pass the country parameter, including a concrete AU/NZ example to distinguish structural patterns from real problems. This effectively routes agents between this tool and its sibling 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?

With readOnlyHint=true already covering safety, the description adds useful behavior: keyless cacheability, per-UTC-day rollup granularity, series-start semantics, and the country echo. It does not describe exact JSON field names, but the data content is sufficiently specified for a read-only history 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?

The description flows from headline to network-series details to country variant, with most sentences earning their place. Minor noise includes the 'issue #716' parenthetical and slight redundancy between the headline and the first 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?

There is no output schema, so the description carries the return-value burden; it does so by stating point contents, series-start behavior, and country-scoping results. It could be more explicit about the exact response structure, but nothing essential is missing 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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics for `country`—same series shape, echoed back, and a later series start—while to/from are already fully described by 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 identifies the resource (network compliance) and the temporal dimension ('one point per UTC day... over time'), making it easy to distinguish from a current-snapshot compliance endpoint. It lacks an explicit retrieval verb in the description itself, but the intent is unmistakable.

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 clear context for both invocation modes: omit `country` for the network trend or pass `country` for a single-country trend, including the later series-start date for country rollups. It does not explicitly contrast with `get_compliance_stats` or state when-not to use this tool, so it stops short of a 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?

Beyond the readOnlyHint annotation, the description reveals the return structure (daily series, all-time monthly rollup), the data source (hourly churn rollup), and an important edge case ('valid but unknown country returns empty arrays'). Also notes 'keyless-cacheable' behavior. No contradiction with 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?

Three sentences cover purpose, output shape, edge case, and caching, with no filler. The most important information is 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?

No output schema exists, so the description carries the burden of describing returns. It explains the series types and the edge case, but could be more explicit about the exact array fields. Overall adequate for the tool's moderate 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%, so parameters are already documented. The description adds semantic context for the country code (valid but unknown -> empty arrays) and clarifies that from/to bound the daily series. This provides extra meaning beyond the raw 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 resource and scope: 'Per-country participant churn' and 'New (joiner) vs departed (leaver) participants for one country'. It distinguishes from sibling tools like get_access_point_churn by focusing on country-level data, and specifies the output shape (daily series + monthly rollup).

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 usage context is implied by the name and description (for country-level churn), but there are no explicit alternatives or when-not-to-use conditions. Sibling tool names exist but are not referenced, so the agent must infer when this tool is the right choice.

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?

Beyond the readOnlyHint annotation, the description adds meaningful context: unknown countries return empty lists, company_coverage semantics and empty providers_by_company for unenriched markets, and keyless-cacheability. This enriches the agent's understanding of edge cases and output interpretation.

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 the main purpose and then provides necessary detail in a compact set of sentences. It includes some technical specifics (issue #467) that may be unnecessary but does not waste words 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?

With a single parameter and no output schema, the description fully covers the return fields, ranking logic, and edge cases. It provides enough information for an agent to know what the tool returns and how to interpret it, making it contextually complete.

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 already provides 100% coverage for the single parameter (code) with a clear description. The tool description does not add syntax details but does clarify the country context and behavior for unknown codes, which is marginal value. 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 it lists access points serving a country with two ranking metrics, giving a specific verb and resource. It distinguishes itself through country-scoped ranking but does not explicitly name sibling alternatives like list_providers.

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 intended use is implied: when you need country-level provider rankings. However, there is no explicit statement of when to use this tool over alternatives or exclusions, so guidance is only implicit.

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?

Beyond the readOnlyHint annotation, the description adds useful behavioral details: an unknown family returns an empty 'doctypes' array, and the result is keyless-cacheable. This helps the agent anticipate edge-case responses and cache semantics.

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 compact and front-loaded with the core concept, followed by concrete output details and edge-case behavior. The internal reference '(issue #647)' adds little value for an AI agent and slightly reduces focus, but overall the structure is 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 single-parameter, read-only tool with no output schema, the description provides the key output fields, the empty-result behavior, and cacheability. It could also state the exact return container or an explicit when-to-use clause, but nothing essential is missing for basic 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%, so the 'family' parameter is already fully documented with examples. The description does not add extra meaning beyond reinforcing that doctypes are scoped within one family, which matches the baseline for full schema coverage.

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 identifies the resource ('concrete document types within one family') and specifies the output fields: local name, version, participant count, and share of the family. It lacks an explicit verb like 'returns' and does not directly contrast with sibling tools, but the resource and scope are unambiguous.

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 given about when to choose this tool over alternatives such as get_doctype_stats or get_doctype_stats_history. The intended use is only implied by the resource description, and no exclusions or alternatives are mentioned.

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 meaningful behavior beyond the readOnlyHint annotation: the country is derived from the participant identifier's ICD, unresolved identifiers bucket as `ZZ`, unknown families return an empty `countries` array, and the result is keyless-cacheable. It also indicates each entry carries a share of the family total. No contradiction with 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 compact and front-loaded with the core purpose, followed by derivation details and edge cases. The internal reference `(issue #652)` is extraneous noise for an AI agent, but the remaining sentences are short and informative.

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, the description does a good job of explaining the result shape: a `countries` array, per-country shares, the `ZZ` bucket, and empty behavior for unknown families. However, it does not specify exact output item field names or the share's type/format (e.g., decimal ratio vs percentage), which would make it fully self-contained.

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 schema already defines `family` as the doctype family name with examples. The description reinforces the family concept and mentions the unknown-family empty-result behavior, but adds little new parameter-level meaning beyond what the schema and annotations already provide.

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 defines the resource: a single doctype family's receiving participants aggregated by ISO-3166 alpha-2 country, with each country's share of the family total. It distinguishes itself from siblings like get_doctype_family_providers by focusing on receivers rather than providers, and from get_doctype_family by adding the country-slice dimension.

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 intended use is implied: call this when you need a receiver-by-country breakdown for one document family. However, it does not explicitly state when not to use it, nor does it reference alternatives such as get_doctype_family_providers for a provider-side equivalent.

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?

Beyond the readOnlyHint annotation, the description discloses meaningful behavioral details: attribution via SMP-hosted footprint, omission of participants whose host maps to no known provider, empty `providers` array for unknown families, and keyless-cacheability. These details materially affect interpretation of results and are exactly the kind of context annotations do not provide.

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 compact and front-loaded, leading with the core definition and then covering edge cases. The issue reference '#652' is marginally useful context but not essential for invocation; overall, every substantive sentence earns its place.

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 read-only lookup with no output schema, the description covers the mapping rule, exclusion behavior, unknown-family behavior, and caching, which is enough to invoke the tool correctly. It stops short of enumerating exact output field names, but the phrase 'each with its share of the family total' conveys the essential response shape.

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 `family` already includes its type and realistic examples. The description adds only a small behavioral clarification that an unknown family returns an empty array, but it does not need to compensate for missing schema detail.

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 defines the resource as 'one document family's receiving participants' and the grouping dimension as 'hosting provider,' with each provider's share of the family total. This distinguishes it from sibling tools like get_doctype_family_countries by the slicing dimension, though it stops short of naming a sibling 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 intended use is implied: call this when you need provider-level breakdowns for a single doctype family. However, it does not explicitly state when to prefer this over get_country_providers or get_doctype_family_countries, nor does it describe exclusion cases for 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?

Annotations declare readOnlyHint, and the description adds non-obvious behavioral detail: results come from pre-computed rollup tables, are edge-cached, and are keyless-cacheable. This helps the agent understand performance and consistency expectations beyond the read-only 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?

The description is compact and front-loaded with the key term, then expands with concrete dimensions. Minor redundancy exists between the heading phrase and the first sentence, but no sentence is wasted.

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?

Because there is no output schema, the description does the work of explaining what the result will represent (per-family shares, wildcard bucket, denominator). It is adequate for a zero-argument read-only tool, though it could explicitly state the return shape (list vs table).

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 tool has zero parameters and the schema coverage is 100%, so there is nothing for the description to document. Per the baseline for 0-parameter tools, this is handled appropriately.

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 the resource ('document-type landscape') and specifies the content: per-family participant share, the wildcard-doctype bucket, and the participant denominator. It does not use an explicit verb like 'returns', but the topic is specific enough to separate it from generic stats tools; its relationship to get_doctype_stats_history is only implied.

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 given about when to choose this tool over siblings such as get_doctype_family or get_doctype_stats_history. The edge-cached/pre-computed phrasing implies a fast current snapshot, but there is no explicit when-to-use or when-not-to-use information.

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 readOnlyHint annotation already covers the read-only safety profile. The description adds a useful data-source detail ('from the doctype history rollup') and the 'Keyless-cacheable' behavior, but does not elaborate on caching implications or return shape. This is adequate but not deeply transparent.

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 deliver the core purpose, temporal granularity, metric, data source, and cacheability with no filler. The main idea is front-loaded in the first sentence, making it quick for an agent 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 simple read-only history tool with two optional, fully documented parameters and no nested output, the description sufficiently explains what is returned: per-day participant counts by family. It could be strengthened by explicitly noting the relationship to get_doctype_stats, but it is otherwise complete.

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 description does not need to restate parameter meanings. It reinforces the UTC-day and historical framing, which aligns with the from/to date parameters, but adds no new parameter-level detail 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 returns document-type landscape history with a specific unit of analysis: per UTC day, participant count per family. This distinguishes it as a historical time-series counterpart to the current-state tools, though it does not explicitly name or contrast a sibling 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 temporal phrasing ('over time', 'per UTC day', 'history') implies this is for historical trends rather than current snapshots, and the from/to parameters support that use. However, it does not explicitly state when to choose this over get_doctype_stats or provide any 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?

Annotations already declare readOnlyHint=true, but the description adds meaningful behavioral context: it lists the returned categories, explains the effect of `?at=`, and describes the conditional publishability and verification caveat of `profile`. It does not cover auth, rate limits, or pagination, but those are less critical for a read-only host lookup.

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 the core purpose and then provides relevant operational details in a compact paragraph. It is dense but not bloated, and every clause contributes useful context.

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, the description usefully enumerates the main returned data and explains the `profile` field's conditional behavior. It remains incomplete regarding selection against sibling tools and does not describe pagination or error behavior, but it is sufficient to call the tool 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 the schema already documents both parameters. The description adds clarifying value for `at` (point-in-time state), but offers no additional detail for `hostname` and mentions `profile` as an output rather than a parameter. 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 uses a clear verb+resource ('Get a host's current state') and enumerates the returned information (role, verdict, network attribution, TLS certificate, provider). It does not explicitly differentiate itself from siblings like get_host_software or get_host_uptime, so it falls short of a 5.

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 current state and the `?at=` parameter implies when the tool is useful (current vs. point-in-time host state). However, there is no explicit guidance on when to choose this tool over sibling alternatives such as get_host_software or list_hosts.

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 provides substantial behavioral detail beyond the readOnlyHint annotation: it explains the version axis including release staleness, lanes, lag, exactness, and advisories. It also clarifies null vs. zero-count semantics ('all-zero counts mean tracked and clean, which is a different statement'), which is exactly the kind of nuance an agent needs to interpret results correctly. This goes beyond the annotation's simple read-only hint.

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 detailed but somewhat dense and runs on, particularly the parenthetical about lanes and the long sentence about exactness. It front-loads the core purpose well but then dives into complex details that could be more concisely structured. The length is justified by the complexity of the return data, but it could be better organized for readability.

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 complexity of the response (multiple roles, version staleness, advisories, null semantics) and the absence of an output schema, the description is quite complete in covering the key aspects an agent needs to understand the return data. However, it doesn't mention the output format (e.g., JSON structure) or how to interpret 'market tier' (which appears at the end without explanation). Overall, it's strong but with minor 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?

The input schema already describes both parameters (hostname and at) with reasonable clarity, and schema coverage is 100%, so the baseline for this dimension is 3. The description adds value by explaining the effect of `at` (point-in-time state) and repurposing it in the context of release staleness, though it doesn't add new syntax or format details beyond the schema. The extra clarity about `at` justifies a 4.

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 host's software fingerprint' and elaborates that it returns detected software across all roles, including vendor, version, hosting, confidence, timestamps, and evidence. This is specific and distinguishes it from siblings like get_software (which likely returns software-level data) and list_host_software (which lists multiple hosts' software).

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 that this tool focuses on a single host's software with optional point-in-time state (`?at=`), but it does not explicitly state when to use this tool versus alternatives like get_host, get_software, or list_host_software. There is no mention of when not to use it or how it differs from similar tools, which is a gap for an agent choosing among many siblings.

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?

Beyond the readOnlyHint annotation, the description discloses key behavioral traits: it returns a per-location rollup including __all__, supports date-range windowing with half-open semantics, and is cursor-paginated. These details are not present in the annotation and add meaningful context for the agent.

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 succinct sentences. The first sentence delivers the primary purpose immediately, and the second elaborates on key details without redundancy. Every phrase earns its place, and there is 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?

Given the tool's complexity (7 parameters, aggregate levels, pagination) and lack of an output schema, the description covers the main functional aspects: aggregate ladder, per-location rollup, windowing, and cursor pagination. It does not describe the exact return fields of an uptime aggregate, but the schema and annotations largely compensate.

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 already provides comprehensive descriptions for all 7 parameters with 100% coverage, achieving the baseline. The description adds minimal parameter-specific meaning, mostly rephrasing concepts like resolution and windowing already 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 opens with 'Get a host's uptime aggregates,' a specific verb and resource combination that clearly states the tool's function. It further differentiates from siblings by detailing the aggregate ladder, per-location rollup, and optional windowing, which distinguishes it from other host/network 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?

The description implies usage for retrieving uptime aggregates at various resolutions and locations, with windowing and pagination. It provides clear context for when to use the tool but does not explicitly mention exclusions or alternatives, such as using get_host for basic host details or list_hosts for enumeration.

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 provide readOnlyHint=true, and the description adds meaningful behavioral context beyond that: it explains the tool returns counts of participants checked, failures, and violation rates, and that results are 'Ordered by violation count, busiest first.' This gives a clear picture of output structure without contradicting the read-only 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?

The description is compact and front-loaded with the essential purpose ('Peppol ID quality summary'), followed by a concise but informative breakdown of what the summary contains and how it is ordered. Every sentence adds value with no fluff or repetition.

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, parameterless, read-only tool, the description fully covers what the agent needs to know: the aggregation level (per-scheme), the metrics provided (participants checked, failures, violation rate), and ordering. Given the lack of an output schema, the description sufficiently explains the return content without missing critical 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?

The input schema declares zero parameters, so there are no parameter semantics to describe. The description thus correctly focuses on output semantics. Baseline of 4 is appropriate for a no-parameter tool.

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 identifies the tool as a 'Peppol ID quality summary' with specific details about per-scheme (ICD) aggregation of structural identifier checks. It distinguishes itself from siblings like list_id_quality_malformed and get_id_quality_hosting by focusing on summary statistics rather than listing individual malformed IDs or host-specific data.

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 summary-level per-scheme quality view is needed, mentioning 'summary' and 'resulting violation rate.' However, it does not explicitly state when to prefer this tool over alternatives such as list_id_quality_malformed or get_id_quality_hosting, nor does it provide clear exclusion criteria.

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 include readOnlyHint=true, and the description does not contradict this. It adds behavioral context by explaining that results are ranked by malformed-id count and that totals cover the filtered set, going beyond the basic read-only 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?

The description is two sentences: a concise headline followed by a detailed summary. Every word adds value, with no redundancy or fluff.

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 rollup with no output schema, the description adequately explains what is returned (Access Points, SMPs, ranking, totals) and how filtering works. It lacks explicit return structure but is sufficient for a tool of 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?

The input schema covers all 4 parameters with descriptions, so baseline is 3. The description mentions the scheme, reason, and q filters, confirming their role, but does not add new semantic meaning 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 this tool provides a hosting rollup for malformed identifiers, listing which Access Points and SMPs serve them. It distinguishes itself from sibling list tools by being an aggregated view, with a specific scope and resource.

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 as a companion to the malformed list tool ('honouring the same filters as the malformed list'), but does not explicitly state when to choose this over get_id_quality or list_id_quality_malformed. Context is clear, but exclusions and direct alternatives are not provided.

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 declare readOnlyHint=true, but the description adds substantial behavioral context: counts are (hostname, role) pairs and can double-count; pre-2026-08-15 unresolvable hosts were recorded as 'down'; the series starts on 2026-07-21; 'from' is clamped; and the data is keyless-cacheable. This goes well beyond the read-only hint and protects against misinterpretation.

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 a one-line summary and then expands into necessary caveats and temporal boundaries. Every sentence adds useful information, though a few implementation details ('derived from the temporal verdict table in one windowed pass') are slightly beyond what an agent strictly needs.

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 there is no output schema, the description does a good job explaining the returned data's semantics: daily granularity, verdict counting, pairing behavior, historical caveats, and date clamping. It could be slightly more explicit about the exact response shape or verdict values, but for a simple two-parameter history tool it is substantially complete.

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 schema already documents defaults, inclusivity, UTC format, and clamping. The description repeats the clamp behavior but adds no new parameter-level meaning beyond what the schema provides, so the 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 opens with a specific verb+resource ('Get the network verdict history') and then defines the exact scope: host verdict mix per UTC day, counted by verdict. The resource is clearly distinct from sibling history tools like get_participant_history or get_doctype_stats_history, so an agent can tell where it belongs.

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 when to use it — when you need host verdict mix over time — but it never states this explicitly nor names alternatives such as get_network_summary. It provides clear context about data granularity but no direct when/when-not guidance, so it stays at the implied-usage level.

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 useful behavioral context beyond the readOnlyHint: it specifies the aggregation scope (last 24h), the types of data returned, and that the freshness measurement refers to the Peppol Directory export behind every other endpoint. However, it does not detail the output shape or any aggregation quirks, which could matter when an agent interprets the result.

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 concise, information-dense sentences. The main action is front-loaded, and every clause adds distinct information about the tool's output without redundancy.

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 parameterless, read-only summary tool, the description covers the essential output components and time window. It is slightly incomplete only in not clarifying how this relates to the generic get_summary sibling, but the content list makes the scope understandable.

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 tool takes zero parameters, so the schema already communicates everything needed. The description's mention of the time horizon and data categories adds mild context, but no parameter-specific semantics are required.

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 identifies a specific resource ('network summary') and enumerates the exact contents: host verdict counts, open incidents, anomalies in the last 24h, plus freshness of the Peppol Directory export. This makes the tool's function clear, though it does not explicitly differentiate itself from the similarly named sibling get_summary.

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 a use case (top-level network overview) by listing aggregate counts and recent anomalies, but it provides no explicit when-to-use guidance or exclusions relative to other get_* tools. An agent must infer when this summary is appropriate rather than being told directly.

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, and the description adds meaningful behavioral context by enumerating the exact fields returned and by noting edge cases ('Discovered participants carry no card; unmatched participants carry company: null'). This goes beyond the basic operation and helps set expectations for response shape, even though it doesn't discuss error handling or auth.

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: the first states the core purpose immediately; the second enumerates included components and edge cases. Every sentence earns its place 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?

With a single parameter, a readOnly annotation, and no output schema, the description covers the main aspects well: what is returned and a couple of edge cases. The phrase 'unmatched participants' is slightly ambiguous (whether it means participant not found or company not matched), so a perfect 5 would require clearer error/not-found semantics.

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%—the 'id' parameter is fully documented as a canonical 'scheme::value' Peppol identifier with an example. The description adds no additional meaning to the parameter, so the baseline of 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 opens with a specific verb+resource: 'Get a participant's current state', then enumerates exactly what that includes (directory presence, SML registration, SMP, business card, endpoints, etc.). This clearly distinguishes from siblings like get_participant_history (current vs history) and list_participants (single vs list).

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 'current state' provides clear context for when to use this tool—when you need a snapshot of a participant's current data rather than history or statistics. The list of components also hints at use cases. However, it does not explicitly name alternatives or exclusions such as 'for historical data use get_participant_history'.

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?

Beyond the readOnlyHint annotation, the description thoroughly discloses complex behavior: the two-lane merging logic (SMP vs AP), the exact verdict definitions (available/degraded/unreachable/no_data), how degraded counts as available for uptime, the monthly target semantics (not contractual), and temporal attribution (pre_epoch). This goes far beyond what the annotation provides and avoids any contradiction.

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 lengthy but well-structured: a one-line purpose, then a detailed but organized explanation of semantics and return content. Each sentence contributes substantively (merge logic, verdict definitions, return fields, historical scope). It is appropriately detailed for a tool with complex behavior, though slightly verbose in the middle section.

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 complexity and the absence of an output schema, the description fully specifies the return contents (per-lane UptimeBuckets, combined lane, headline uptime ranges, service-level target, host-change markers, incidents), historical coverage, and edge cases like pre_epoch attribution. An agent has enough information to understand exactly what it will receive and how the data is derived.

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 schema already documents id, to, from, and resolution with clear meanings. The description adds minimal new semantic value—only the note about pre_epoch attribution, which is contextual but not tied to a specific parameter. The baseline of 3 is appropriate since the schema carries the parameter documentation load.

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 a participant's measured availability' and elaborates on the probe-measured reachability of one Peppol ID over time. The description clearly defines what the tool does and the return structure, making it distinct from siblings like get_participant_stats or get_participant_history, even without naming them.

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 explains the tool's scope and semantics but provides no explicit guidance on when to use it versus alternative participant-related tools (e.g., get_participant_stats, get_participant_history). Usage context is implied from the function name and detailed output, but no when-to-use or when-not-to-use directives are given.

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 declare readOnlyHint=true, and the description's 'List' is consistent. It adds behavioral context beyond the annotation: newest-first ordering, cursor pagination, and the specific fact families included, which is useful for the agent.

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 concise sentences: the first front-loads the core action, the second adds scope, ordering, and pagination details. No unnecessary words or repetition.

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 readOnlyHint and full schema coverage, the description explains scope, ordering, and pagination. However, it does not describe the return structure (no output schema exists), which is a minor gap but not critical for a listing 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?

Schema coverage is 100%, with each parameter already described in detail. The description only adds behavioral context (cursor-paginated) rather than further parameter semantics, so it does not exceed the baseline for well-documented schemas.

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 'List' and identifies the resource as 'participant's temporal history' with explicit scope (directory/card/registration/SMP fact families), ordering, and pagination. This clearly distinguishes it from siblings like get_participant_stats_history and list_participant_events.

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 on what data is covered (temporal rows across specified fact families) and mentions cursor-paginated, implying when to use it. However, it does not explicitly state alternatives or when not to use this tool, so it stops short of a 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?

Beyond the readOnlyHint annotation, the description discloses meaningful behavioral details: derivation from business-card RegistrationDate or first-seen, the handling of unknown/seed tail (reported only in coverage, never bucketed), and keyless-cacheability. It adds significant context without contradicting 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 compact and well-structured, with the title line followed by a brief explanation. The reference to 'issue #222' is somewhat extraneous, but the rest is informative and to the point.

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 has one optional parameter and no output schema, the description provides solid context: what the curve represents, the join date derivation logic, coverage categories, and the unknown tail behavior. It is sufficiently complete for an agent to select and invoke correctly, though it stops short of specifying the exact response shape.

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 the single 'bucket' parameter, including its enum, default, and description. The tool description does not add additional parameter context beyond the schema, which is sufficient.

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 identifies the tool as returning a 'Network joiners curve' with joiner counts bucketed by derived join date. It distinguishes from sibling tools by calling it 'The real onboarding curve' and specifying whole-network coverage split, making it distinct from related participant/network 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?

The description implies usage for onboarding/joiner analysis with a coverage split, but it does not explicitly state when to use this over siblings or provide exclusions. The context suggests it's the go-to for joiners curves, but no direct alternatives are named.

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?

Beyond the readOnlyHint annotation, the description discloses two execution sources (rollup vs slice) with their trade-offs, an internal cap of 10,000 participants, degraded responses with null mixes, and the exact semantics of sparse counts (sums below participant_count, _other_ bucket). This is rich, non-obvious behavioral context that an agent needs to set expectations.

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 long but well-structured with clear section headings ('TWO SOURCES', 'BOUNDED BY DESIGN') and each paragraph adds a distinct piece of essential context. It is front-loaded with the primary purpose and then progressively details behavior. Slightly wordy in places, but the complexity of the endpoint justifies the length.

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?

Despite having no output schema, the description fully explains the response shape: the source field, refreshed_at, degraded flag, participant_count, and the ap_mix bucket. It also covers edge cases like sparse enrichment and the handling of excluded values. An agent can invoke and interpret the result correctly without missing information.

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 already covers all 18 parameters with detailed descriptions, examples, and exclusion semantics. The description adds no new parameter-level meaning; it only refers to 'the same names and shapes as GET /v1/participants' and explains that some filters cannot be expressed (leading to degraded mode). Since schema coverage is 100%, 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 opens with a specific verb and resource: 'Get a filtered participant breakdown,' then spells out the exact grouping dimensions (country, entity type, NACE sector, size class, region, Access Point) and the filtered-slice context. It clearly distinguishes this from siblings by emphasizing it's a breakdown rather than raw participant lists or statistics, and even names the fallback endpoint for a whole-network view.

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 when-to-use guidance: a request with no narrowing uses the rollup source; a narrow request uses the live slice; a too-wide or unsupported filter returns degraded and instructs callers to fall back to GET /v1/stats/participants. It also names the unsupported filters (doctype, transport_profile, q, host, sub_provider) so an agent can predict behavior.

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 declare readOnlyHint=true, but the description adds substantial behavioral context: it is derived from an hourly rollup, it is keyless-cacheable, and it explains the distinction between total_count (all IDs ever) and registered_count (LIVE IDs). This goes well beyond the annotation and informs the agent about data freshness and caching semantics. No contradiction with 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 compact (three sentences) and front-loads the core purpose. It uses a clear title and then provides necessary details without fluff. Every sentence adds value: the facets, the count semantics, and the caching note. Well structured.

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, the description must explain what is returned. It does so thoroughly: lists the facet dimensions, mentions registered share and provenance split, explains total_count vs registered_count, and notes the hourly rollup freshness. This is sufficient for an agent to understand the tool's output without needing an output schema.

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 zero parameters, so the input schema is empty. The baseline for zero parameters is 4. The description doesn't need to elaborate on parameters; it focuses on output semantics, which is appropriate. Since there are no parameters, no additional information could be added.

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 identifies the tool as providing global participant facet counts across multiple dimensions (country, scheme, smp, ap, doctype, transport_profile), plus registered share and provenance split, with an estimated total. It distinguishes itself from sibling tools like get_participant (individual) and get_participant_stats_history (historical) by focusing on current rollup stats. The verb 'get' and resource 'participant stats' are specific and unambiguous.

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 notes it is keyless-cacheable and safe for the marketing site to hit directly, which gives a usage context. However, it does not explicitly state when to use this tool instead of get_participant_stats_history or other stats tools. The guidance is implied (current vs historical) but not spelled out as an alternative, so the agent must infer.

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. The description adds useful behavioral context: 'Keyless-cacheable' indicates caching behavior, and 'History accrues from the day the feature shipped' clarifies data availability. This goes beyond the annotation without contradicting it, though it omits details like rate limits or consequences of no data.

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: three short sentences with no wasted words. The title is front-loaded, and the subsequent sentences efficiently convey the core concept and key behavioral traits.

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 tool with 5 parameters and no output schema, the description covers the core concept (daily time series per facet) and adds caching and data start date. However, it lacks details on return format, how multiple keys combine (logical OR vs AND), or behavior for dates with no data. Given the complexity, there are clear 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 coverage is 100%, so the baseline is 3. The description does not add explicit parameter-level meaning beyond the schema's own descriptions. However, the high-level context (e.g., 'facet dimension' aligns with the dimension parameter) provides some supporting semantics, but no additional depth.

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 identifies the tool as providing a daily time series over a participant facet dimension, mentioning adoption curves and QoQ trends. It distinguishes from siblings like get_participant_stats and get_participant_history by specifying the time-series nature per facet, but doesn't explicitly compare or contrast with similar 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 explicit guidance on when to use this tool versus alternatives. The description implies it's for single-facet daily history, but it does not state exclusions or recommend other tools for different use cases (e.g., get_participant_history for per-participant history).

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 annotation readOnlyHint=true already indicates a safe read operation. The description adds that the provider is 'navigable to its seats and each seat's observed hosts,' providing context about the returned structure. However, it does not mention rate limits, pagination, or other behavioral details, so it only modestly extends the 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?

The description is two short sentences, front-loaded with the core purpose and a clarifying second sentence. It is concise with zero redundancy 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?

For a simple single-parameter read-only tool with no output schema, the description provides sufficient context: it identifies the resource and hints at the navigable structure. It could be more explicit about the response being a single provider object, but the get verb and slug parameter imply this.

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 covers 100% of parameter descriptions, with 'slug' described as 'The curated provider slug.' The tool description repeats the 'curated provider' wording but adds no new semantics. Baseline 3 is appropriate given the high schema coverage.

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 gets a 'curated provider' and elaborates that it is navigable to seats and observed hosts. This distinguishes it from siblings like list_providers and get_provider_sla, though it does not explicitly name them. The verb 'Get' and the specific resource make the purpose clear.

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 does not provide any guidance on when to use this tool versus alternatives such as list_providers or get_provider_sla. It implies usage through the slug parameter and 'navigable' wording, but there are no explicit when-to-use or when-not-to-use instructions.

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?

Beyond the readOnlyHint annotation, the description reveals ordering (worst uptime first, providers with no checks last), data freshness (materialized hourly by batch runner), and pagination (next_cursor always null). These are non-obvious behavioral details that help the agent set expectations.

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 with no redundancy. The first sentence states the core purpose, the second describes the data returned and ordering, and the third covers materialization and pagination. Every sentence carries meaningful 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 this is a simple list endpoint with one optional parameter, no output schema, and a readOnly annotation, the description covers all essential aspects: what data is included, the ordering, freshness, and pagination behavior. It is sufficiently complete for an agent to invoke and interpret results 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?

The schema provides 100% coverage for the single `period` parameter, fully explaining the 30d/90d options and default. The description does not add further parameter-specific semantics, so the baseline score of 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 opens with 'List provider SLA scorecards,' using a specific verb and resource, then elaborates on the exact contents (checks-weighted uptime, incident count, downtime minutes, worst host). This clearly distinguishes it from sibling tools like get_provider_sla_by_key, which would target a single provider.

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 for viewing all providers' SLA scorecards over a trailing period and notes the hourly materialization, which is useful context. However, it does not explicitly mention alternatives or when to prefer get_provider_sla_by_key for a specific provider, so the guidance is only implied.

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 readOnlyHint annotation covers the safety profile, and the description adds behavioral detail: empty items when no SLA data exists and the structure of one scorecard per trailing period. This goes beyond the annotation, though it does not cover error responses or authentication specifics.

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 compact and clearly structured, opening with the core verb and resource. The following sentences add distinct value: output periods, parameter source, and empty-items behavior. No filler or redundancy.

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 tool, the description provides sufficient information to select and invoke it: purpose, key semantics, output structure, and no-data behavior. No output schema exists, but the description covers essential return semantics clearly.

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 enhances the parameter meaning by noting the key is the provider's natural key as reported by GET /v1/providers, adding a source reference beyond the schema's 'provider natural key'.

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 gets a provider's SLA scorecards, with specifics about trailing periods (30d and 90d). The 'by_key' designation and natural key reference make the resource and scope unambiguous, even without explicit sibling differentiation.

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 for when to use the tool: when retrieving SLA scorecards for a specific provider by natural key. It explains the output includes one scorecard per trailing period, but does not explicitly mention alternatives or when not to use it.

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 readOnlyHint=true already noting the read-only safety, the description adds valuable context: the tool requires no API key, returns a public subset, and the response shape matches a known list item. This goes beyond the annotation to disclose access requirements and data scope.

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 focused sentences, front-loaded with the core purpose, then concise clarifying details. Every word earns its place 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?

For a simple single-parameter read-only tool, the description is complete: it specifies the return shape, access requirements, and scope. No output schema exists, but the description sufficiently covers what the agent needs to select and invoke this 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?

Schema coverage is 100% and the parameter description 'The curated provider slug' is already in the schema. The tool description adds no further meaning about the slug, so it meets the baseline but does not elevate it.

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 fetches a public provider profile, using the specific verb 'Get' and resource 'public provider'. It distinguishes from siblings like get_provider and list_public_providers by emphasizing it is the 'FREE, crawlable public subset' and 'same shape as a GET /v1/providers/public item'.

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 provides clear context: this is the public, no-API-key subset for a single curated provider, which implies use when unauthenticated public data is needed. However, it does not explicitly mention alternatives (e.g., use get_provider for full data) or state when not to use it, so it falls short of full alternative 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?

The readOnlyHint annotation already declares the tool as read-only. The description adds useful context about the provider mapping fallback (verified vs. cert-CN unverified) and that hosts are 'observed operating,' but it does not disclose additional behavioral aspects like error handling, authentication, or rate limits. This is a moderate addition over the 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?

The description is concise, with just two sentences. The first sentence 'Get a seat' front-loads the action, and the second sentence provides essential context. No filler or redundant information is present.

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 read-only tool with one required parameter and no output schema, the description adequately describes the return value (provider and hosts). It is reasonably complete, though it could mention error cases or response structure explicitly. The absence of an output schema places more responsibility on the description, which it largely fulfills.

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 100% coverage for seatId with a clear description and example. The tool description does not add parameter-specific details, but it does explain what a seat is, indirectly aiding comprehension of the identifier. This meets the baseline for high schema coverage.

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 'Get a seat' and then defines what a seat is: 'A Peppol certificate seat: its embedded provider (verified mapping or unverified cert-CN fallback) and the hosts it was observed operating.' This clearly identifies the resource and its unique characteristics, distinguishing it from siblings like get_provider or get_host.

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 no guidance on when to use this tool versus alternatives. It does not mention specific scenarios, exclusions, or when to prefer a different sibling tool, leaving the agent without explicit usage direction.

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?

Beyond the readOnlyHint annotation, the description discloses important behavioral details: rates are per 1,000 registrations and null for seats with no registrations; network percentiles include all seats with registrations, counting no-findings as 0; snapshot_date is null for unscanned seats. These edge cases and calculation semantics are not available from annotations or schema.

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 moderately detailed but front-loaded with a clear one-sentence summary, followed by necessary semantic clarifications. The narrative about the Peppol Authority's scan adds context but is slightly embellished; still, every substantive sentence provides definitional or edge-case value.

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, the description does the work of explaining what the tool returns: registrations, OPEN findings by rule, daily trend, and network comparison. It also defines null behavior and the daily rollup semantics. It stops short of an explicit response shape, but for a scorecard tool this is a strong, usable 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 description coverage is 100%, so the baseline is 3. The schema already documents seatId and days with examples and bounds. The description adds conceptual context around daily rollups and rate calculation, but does not add new parameter-level meaning beyond what the schema states.

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 opens with a specific verb and resource: 'Get a seat's compliance scorecard.' It then enumerates the content (registrations, OPEN findings by rule, daily trend, network position), making it clear this is a single-seat compliance view, distinct from sibling tools like get_compliance_stats or list_compliance_findings.

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 clear context: it is a per-seat compliance posture, described as what a Peppol Authority's periodic scan reports. It does not explicitly name alternatives or state when not to use it, but the scope ('One seat's compliance posture') differentiates it from network-level siblings.

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 readOnlyHint=true, safety is already disclosed. The description adds behavioral context by specifying the trailing periods (30d and 90d) and that an empty items array is returned when the seat has no SLA data. This goes beyond annotations and provides meaningful return-behavior transparency.

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: three short sentences, front-loaded with the main purpose, and every sentence earns its place. There is 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?

For a simple one-parameter tool with no output schema, the description covers the purpose, parameter provenance, and return behavior (trailing periods, empty items). However, it does not describe the inner structure of a scorecard (e.g., fields like score or status), which would be helpful given the absence of an output schema. This minor gap prevents a 5.

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 already fully documents seatId with a precise example. The description adds extra semantic value by explaining that seatId is the seat identifier as reported by `GET /v1/aps/{key}` on `seats[].seat_id`, which helps agents extract the value from another endpoint's response. This goes beyond the schema's basic type/description.

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 starts with 'Get a seat's SLA scorecards', a specific verb+resource that clearly distinguishes from sibling tools like get_seat or get_provider_sla. It further clarifies the scope by stating it returns one scorecard per trailing period (30d and 90d), leaving no ambiguity about what the tool does.

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 context on when to use the tool (for a seat's SLA scorecards) and explains how to obtain the seatId via a specific endpoint, which is useful guidance. However, it does not explicitly mention alternatives or exclusion criteria (e.g., 'use get_provider_sla for provider-level SLA'), so it falls short of a 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 already provide readOnlyHint=true, and the description aligns by describing a read-only status snapshot. It adds transparency by disclosing the per-zone layout and the specific status fields, which goes beyond the annotation. However, it does not address potential errors or pagination, but this is reasonable for a zero-parameter read-only 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?

The description is exactly two sentences: the first gives the purpose, the second lists the content. It is front-loaded and every phrase earns its place, providing substantial information without fluff or repetition.

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 no parameters, the description compensates by itemizing the returned fields and the per-zone structure. It does not detail the exact JSON format or error behaviors, but for a simple read-only status helper, it provides a sufficiently complete picture for an agent to understand what to expect.

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 tool has zero parameters, so there is no parameter-specific information to add. Per the rubric, a zero-parameter tool receives a baseline score of 4, as the description cannot contribute additional parameter semantics beyond what is inherently absent 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?

The description clearly states 'Get SML/SMK zone status' with a specific verb and resource, then elaborates the exact components returned (quorum verdict, canary breakdown, etc.). It distinguishes itself from sibling tools that target access points, hosts, or participants, making the tool's purpose unambiguous.

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 the agent needs this specific status data, but it does not explicitly state when to use this tool over alternatives or mention any exclusions. There is no reference to sibling tools or conditions, so the agent must infer applicability from the resource name and contents.

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?

Beyond the readOnlyHint annotation, the description reveals meaningful behavior: unknown slug returns 404, `advisory_list` is null when no advisory feed exists versus [] when upstream has published nothing, and advisories are returned newest first. This is substantial behavioral detail the schema and annotations do not provide.

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 but well-organized: first sentence states scope, second defines the engine parameter and error behavior, third details the advisory_list return contract. Minor extras like the issue reference and 'Market tier' add context but could be trimmed without losing essential 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?

Since there is no output schema, the description carries the full burden of explaining the return value. It lists the returned row fields, the advisory fields, ordering, null/[] semantics, and error behavior. For a read-only getter with two documented parameters, nothing critical 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?

The schema already documents both parameters with 100% coverage, so the baseline is 3. The description adds value by explaining the `engine` slug semantics, linking it to the list output, and specifying the 404 failure mode. The `days` parameter gets no extra elaboration, but the schema already covers its range and default.

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 specific verb and resource: 'Get one software product (Market)', then identifies the resource as a catalogue engine slug. It enumerates the returned content (product metadata, host counts, compliance signal, advisory list), which clearly distinguishes it from list-style siblings like list_software.

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 clearly frames this as a single-engine lookup and gives a precondition: `engine` must be a catalogue slug 'as published in `engine` on the list', with an unknown slug resulting in 404. It does not explicitly name alternatives or when-not-to-use conditions, but the single-row scope is clear enough to route an agent 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?

Despite readOnlyHint already declaring the safety profile, the description adds substantial behavioral context: k=5 anonymisation, tail folding into 'other', two-denominator coverage, no bare coverage scalar, live computation, edge caching, keyless cacheability, and no operator naming. These details materially affect how the returned data must be interpreted.

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 but purposeful: it opens with the subject, then explains the exact metrics, denominator treatment, computation method, and caching characteristics. Every clause supplies a meaning or caveat; only the issue number is mildly unnecessary.

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, the description carries the full burden of explaining the return meaning. It covers the metric set, k-anonymisation, denominator nuance, temporal characteristics, and caching. An agent has enough context to select and invoke the tool 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?

The tool has zero parameters and schema coverage is 100%, so the description bears no burden for explaining inputs. The 0-parameter baseline applies: there is nothing meaningful to add beyond what the schema already states.

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 identifies the resource: a current 'Software landscape' of free host software, listing vendor share, version distribution, ASN hosting share, and coverage metrics. It does not use an explicit verb like 'returns' or 'lists', and it does not explicitly distinguish itself from get_software_stats_history, so it loses the top point.

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 text implies this is the current snapshotted landscape ('Computed live ... edge-cached'), which suggests use for current software stats rather than historical ones. However, it never names get_software_stats_history or gives explicit when-to-use/when-not-to-use guidance, so the usage context is only implied.

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?

Beyond the readOnlyHint annotation, the description adds useful behavioral detail: it is computed in 'one windowed pass', grouped by UTC day, host-weighted, k-anonymised, and keyless-cacheable. These details help an agent understand performance, privacy, and response shape semantics.

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 compact, front-loaded with the resource, and every sentence adds value. The heading 'Software landscape history' plus the explanatory sentence and cacheability note are sufficient without 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 a read-only, two-optional-parameter time-series tool without an output schema, the description conveys the time granularity, the metrics, and the date defaults. It doesn't describe row counts, edge cases, or the exact JSON return shape, but an agent has enough context to invoke and interpret 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?

The input schema already fully documents both optional date parameters with defaults and formats. The description adds nothing new about parameter meaning, so the baseline score of 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 states the resource — 'software landscape history' — and the exact output semantics (per UTC day, host-weighted identified/total targets, k-anonymised vendor shares). It is clear enough to distinguish from the non-temporal get_software_stats sibling, though it never explicitly names that alternative.

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 use case is implied by 'over time' and the tool name, but there is no explicit guidance about when to choose this over get_software_stats or other history tools. An agent can infer it is for historical trends, yet the description doesn't state boundary conditions such as 'current snapshot -> get_software_stats'.

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 readOnlyHint already supplied by annotations, the description adds valuable behavioral context: it is a 'public' rollup, so no authentication is implied, and it precisely defines the data scope. It discloses exactly what data is included and excluded, going well beyond the annotation's read-only hint.

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 concise: a short title line followed by one dense sentence enumerating the contents and exclusions. Every phrase adds information, with no 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?

The description fully covers what to expect from the tool (three data components) and what not to expect (host lists, registry, per-host uptime). Since there is no output schema, this enumeration is essential and fully sufficient for a no-parameter read-only 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?

The tool has zero parameters, so the description cannot add parameter-specific semantics. Per the rubric, a baseline of 4 is appropriate for no-parameter tools.

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 retrieves the public dashboard summary and enumerates three specific data components: network-wide host rollup, hourly fleet-average p50 latency trend, and top-10 providers by market share. It also distinguishes itself from siblings by explicitly stating what is not exposed (no host list, full registry, or arbitrary per-host uptime), making its purpose unambiguous.

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 explicit usage context: it is a 'free marketing-dashboard rollup' for public summary data. It also gives a clear when-not by excluding host lists and per-host uptime, implying users should seek other tools for those details. This is sufficient guidance for selecting this tool over the many sibling get/list 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?

The description adds valuable behavioral information beyond the readOnlyHint annotation by stating 'Bounded to 500 rows (never paginated; next_cursor null)'. It also clarifies that the output consists of participant IDs, providing context about the return format. This enriches the agent's understanding without contradicting 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 two sentences long, with the first sentence stating the core purpose and the second providing drill-down and limitation details. It is front-loaded, contains no filler, and every sentence earns its place.

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 4 parameters and no output schema, the description covers the purpose, the drill-down logic, and the row limit/pagination behavior. It states that the result is participant IDs, giving return-value context. The absence of explicit parameter explanations is acceptable because the schema fully covers them, leaving only minor 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?

All parameters are fully described in the schema with 100% coverage, including inclusive date ranges, provider key, and category enum. The description references 'over the period' and 'Provider' but adds no additional parameter-level meaning, so it relies on the schema which already carries the burden.

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 'List participants' and clearly identifies the resource as 'behind a churn category' for a Provider over a period. It distinguishes itself from sibling tools like list_participants by focusing on the churn drill-down context, making the purpose unambiguous.

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 'The drill-down' implies that this tool is used to expand a churn category count, but it does not explicitly state when to use this tool versus alternatives. No exclusions or alternative suggestions are provided, so usage guidance is only implied rather than explicit.

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 declare readOnlyHint=true, and the description adds meaningful behavioral context beyond that: the tool is not paginated (next_cursor is always null), the Provider resolution precedence (curated mapping → exact signing-cert O= string → bare SeatID), and the fact that country-scoped results add extra fields while network-wide fields remain unchanged. This is rich, non-obvious behavior that helps an agent understand what the call will return and how it behaves.

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 compact and front-loaded: the first sentence states the resource and key output fields, followed by the resolution precedence, pagination behavior, and the optional country parameter. Every sentence earns its place, and the most important scoping information appears early.

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 list tool with one optional parameter and no output schema, the description covers the essential behavior: what is listed, how providers are resolved, pagination behavior, and the effect of the optional parameter. It does not enumerate every output field, but the description's mention of member seats, roster size, and country-scoped fields is sufficient for an agent to invoke it correctly. A small gap is that it doesn't explicitly state the default sort order beyond 'busiest first' or describe the envelope structure, but these are minor.

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 already documents the `country` parameter thoroughly (pattern, case-insensitivity, 400 behavior, added fields), so schema coverage is 100%. The description adds the usage context of 'compare providers within one market instead of network-wide', which complements the schema without repeating it. Since the schema carries the heavy lifting and the description adds a small but useful framing, a 4 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 ('List') and resource ('access points'), then defines what an access point is: every Provider in its serving role with member seats and roster size, busiest first. It also distinguishes itself from siblings by explaining the Provider resolution precedence and the non-paginated behavior, which makes it clear this is a directory listing rather than a single-item or churn-focused 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 description gives clear context for when to use the tool: to list access points network-wide or, with `?country=CC`, to compare providers within one market. It does not explicitly name sibling alternatives or state when not to use them, but the 'instead of network-wide' phrasing and the detailed scope semantics provide enough guidance for an agent to select it appropriately.

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 readOnlyHint: true already in the annotations, the description adds valuable behavioral detail beyond the annotation: results are sorted newest-first and paginated via cursor. This is precisely what an agent needs to consume the feed correctly. It doesn't cover response shape or filter semantics, but those are secondary for a read-only list endpoint.

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 with zero filler. The 'newest-first, cursor-paginated' behavior is front-loaded right after the short verb+resource statement, giving the agent the most decision-relevant information first without any wasted words.

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 description is adequate for a straightforward read-only listing where all parameters are self-documented, but it is thin in a few areas: no output schema exists, the description does not clarify whether the fully documented anomaly items (or a feed of metadata) are returned, and the combination semantics of multiple filters (e.g., host vs detector; AND or OR?) is left unexplained.

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 of 3 applies. All eight parameters are individually documented in the schema (host, seat, grade, limit, since, cursor, detector, acknowledged), and the description itself adds no parameter-level context that isn't already in the structured input.

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 ('List') and resource ('anomalies') and adds defining traits: the newest-first, cursor-paginated anomaly feed. This clearly distinguishes it from get_anomaly (single-item fetch), but it does not explicitly differentiate it from the similarly named sibling list_software_anomalies.

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 explicit when-to-use guidance is provided. The description does not explain when to choose this over list_software_anomalies, get_anomaly, or other list tools, nor does it state the default feed scope or how filters should be combined. The usage context is only implied by the 'feed' phrasing.

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 several behaviors beyond the readOnlyHint annotation: cursor-pagination on (day, value), the definition of membership being tied to mover events, and the 404 response for stale handles with advice to re-read the feed. These are significant behavioral details not captured in 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 well-structured with a clear lead sentence, then supporting details about pagination and id semantics. Every sentence adds value, and the content is front-loaded with the primary purpose. It is appropriately concise for the complexity involved.

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 lack of an output schema, the description adequately covers what is needed: it explains pagination, ordering (oldest observation day first), and the staleness behavior. It does not explicitly describe the structure of each returned participant item, but the nature of the tool (listing participant IDs) makes that less critical. Overall, the description is fairly complete.

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 already documents all three parameters with descriptions (coverage 100%). The description adds meaningful semantics for `id` by explaining it is a request-lifetime handle from a specific endpoint and that it can go stale, and for `cursor` by noting it is returned as `next_cursor`. This goes beyond the schema's basic type and pattern 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 function: 'List participants in a bulk AP migration' and further explains it as 'the drill-down: the participant IDs behind one cohort'. It distinguishes itself from sibling tools by specifying it operates on a cohort handle, and it names the source endpoint for that handle, making the purpose unambiguous.

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 clear context: this is the drill-down for a cohort, and it explains that the `id` comes from `GET /v1/stats/cohort-moves`. It advises not to persist ids because they can go stale. While it doesn't explicitly name alternatives, the context makes the intended use 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?

Beyond the readOnlyHint annotation, the description discloses substantial behavioral nuances: cohorts are based on probe-observation day rather than execution day, `top_country` derives from ICD prefixes, `merge_suspect` is a re-evaluated current judgment, and `id` is only request-lifetime. It also explains what the thresholds reject (steady drip, recurring partnership), giving the agent a mental model of the tool's 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 longer than average, but every sentence earns its place by explaining non-obvious semantics or trapping pitfalls. It is front-loaded with the core purpose and detection definition, then organizes filters and output-field caveats in coherent paragraphs. There is no fluff or repetition of schema defaults.

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 list tool with no output schema, the description covers the essential response-field semantics (`top_country`, `merge_suspect`, `peak_day`, `first_day`, `last_day`, `id`), ordering ('largest first'), date-range behavior, defaults, and data-history boundary. An agent has enough context to call the tool correctly and interpret results confidently.

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?

Although the schema already provides 100% coverage of parameter names and defaults, the description adds material meaning: `from`/`to` are overlap bounds tied to the detector's re-clustering window, `min_participants` cannot surface groups below the detector's floor, and `merge_suspect` is a live judgment rather than a frozen flag. This goes well beyond a bare schema and genuinely helps an agent choose and set values correctly.

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 specific verb and resource ('List bulk AP migrations') and immediately distinguishes the tool's subject by defining a 'cohort' with precise detection thresholds. It clearly differentiates this from the sibling drill-down tool by framing the output as the cohort list itself, and it even explains what the returned `id` is for.

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 ample context on when to use the tool: bulk migrations, detection criteria, observation-day semantics, and filter behavior. It does not explicitly name alternative tools or state 'when not to use this,' but the context is clear enough that an agent can infer the appropriate scenario. It misses explicit exclusions or comparison to sibling tools like list_cohort_move_participants.

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 signal readOnlyHint=true, and the description adds substantial behavioral context: deterministic verdicts, newest-first ordering, keyset pagination on a composite key, the open/resolved lifecycle, persistence of `first_detected_at` across rescans, and `meta.facets` on the first page. This goes well beyond what annotations or the schema alone would tell the agent.

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?

Four dense sentences each contribute distinct information: what the tool returns, ordering/pagination, lifecycle behavior, and differentiation from anomalies. There is no filler or repetition of schema content, and the most identifying facts are 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 tool has 9 optional parameters and no output schema, the description covers the operational essentials: deterministic rule-based results, ordering, pagination key, lifecycle transitions, polling convergence, and first-page facets. An agent has enough context to select the tool, set filters, and interpret pagination without major 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%, so the input schema already fully documents all nine parameters, including defaults, enums, and the `since` polling semantics. The description adds no parameter-specific details but does explain global behavior like facets, which is consistent with the baseline-3 expectation when the schema carries the parameter burden.

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 ('compliance findings'), then clarifies the domain further as 'deterministic verdicts against the published rules' with explicit ordering and pagination semantics. It also distinguishes itself from `/v1/anomalies`, so an agent can tell it apart from the most similar sibling without reading schemas.

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 contrasts this tool with `/v1/anomalies`, saying anomalies report observed behaviour rather than rule breaches, which is a clear when-not-to-use signal. It does not enumerate all alternative siblings or spell out an exhaustive 'use this when...' statement, but it covers the main routing ambiguity.

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 readOnlyHint annotation already signals this is a safe read operation. The description adds useful context that the rules are free and public, and that findings are not included here. It does not discuss pagination, result shape, or any access requirements, but for a simple list operation the annotation plus description is adequate.

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 first and last sentences are useful, but the middle sentence is garbled and repetitive: 'how many findings requires, what it applies to, and how severe a breach is' appears twice with broken phrasing. This redundancy undermines clarity and suggests an editing error, so the description is not cleanly 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?

For a zero-parameter, read-only list tool, the description is mostly complete: it identifies the resource and points to the findings endpoint for related data. However, there is no output schema and the description does not clarify the catalogue item structure or pagination behavior, leaving a small but real gap.

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?

This tool has zero parameters, so the baseline is 4. There are no parameter semantics to clarify, and the description appropriately focuses on behavior and scope rather than parameters.

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 'List the compliance rule catalogue,' which clearly identifies the action and resource. It also distinguishes this tool from the related findings tool by explicitly directing findings to `GET /v1/compliance/findings`.

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 context: this endpoint lists the public rules catalogue, while findings are located elsewhere via the findings endpoint. It could be more explicit by naming the sibling tool `list_compliance_findings`, but the separation between rules and findings is clearly conveyed.

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?

Given `readOnlyHint: true` already declares the safety profile, the description adds meaningful behavioral detail: cursor direction semantics, embedded triggered anomalies, and the meta block with facets and timeline chart. The description is consistent with the read-only annotation and enriches it with concrete pagination and payload context.

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 four dense sentences with no filler. The core purpose is front-loaded, followed by pagination semantics, embedded anomalies, and meta information — each sentence adds necessary 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?

The description is surprisingly complete for a 10-parameter list tool without an output schema: it covers ordering, pagination, anomaly embedding, and page metadata. It does not enumerate the exact event payload fields, but the 'typed change event' framing plus the schema's type enum lowers the cost of that omission. Still, an output schema or a more explicit event-shape summary would raise completeness further.

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 each parameter is already documented and the baseline is 3. The description adds value beyond the schema by explaining the different directions of `cursor` vs `prev_cursor`, the 'live polling' use case, and the meta block generated for the first page.

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, 'List global change events,' and key ordering behavior, 'newest-first.' It is clear and distinct from incident/anomaly-related siblings, although it doesn't explicitly name an alternative sibling for comparison.

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 usage context through pagination direction: `cursor` walks older events, `prev_cursor` walks newer events and is 'for live polling.' However, it provides no explicit when-to-use vs when-not-to-use guidance or alternative tool names, so comparative selection is left to the agent's inference.

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 declare readOnlyHint=true, and the description adds meaningful behavior: newest-first ordering and cursor-based pagination. This goes beyond the annotation and the schema to disclose how results are returned, though it does not mention details like auth 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 two short sentences, front-loaded with the primary purpose and immediately followed by key behavioral details. Every word earns its place with no redundancy.

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 five parameters all fully documented in the schema, the description provides the essential runtime behavior (ordering, pagination) not covered by the schema. Since there is no output schema, a brief note on return shape could improve completeness, but the current level is sufficient for a list operation.

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 100% parameter description coverage, so the description does not need to explain parameters. It adds no additional semantic meaning beyond what the schema already offers for the five parameters, matching 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 clearly states 'List a host's incidents', specifying the verb, resource, and scope ('for one host'). This distinguishes it from sibling tools like list_incidents (likely all incidents) and list_hosts (hosts themselves). The added 'newest-first, cursor-paginated' details further clarify behavior.

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 clear context that this tool is for retrieving incidents for a single specific host, which implies when to use it. However, it does not explicitly name alternatives or state when not to use it (e.g., for cross-host incident queries), so it lacks 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?

Annotations already declare readOnlyHint: true, so the safety profile is covered. The description adds valuable behavioral context by specifying exactly what is returned: current verdict, latest latency, 24h uptime, ordering (worst-first), and the network-wide rollup, which goes beyond the 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?

The description is extremely concise: two sentences that front-load the core purpose ('List monitored hosts') and then add essential output details. Every sentence is informative with no wasted words.

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 list tool with no parameters and no output schema, the description provides comprehensive information about the return value: the fields, ordering, and inclusion of a rollup. It fully explains what the agent can expect, making it complete for its 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?

The tool has zero parameters, so the schema provides no parameter semantics. The description correctly omits any parameter details. Baseline for 0 parameters is 4, and there is nothing to add.

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: 'List monitored hosts' with a specific verb and resource. It further distinguishes itself from siblings like get_host and get_network_summary by detailing the unique output: verdict, latency, uptime, worst-first ordering, and a network-wide rollup.

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 for obtaining a broad overview of all monitored hosts, including metrics and a rollup. It does not explicitly name alternatives or exclusions (e.g., 'for a single host, use get_host'), but the context is clear enough for an agent to select this tool when a comprehensive list is needed.

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 read-only safety profile is already in annotations, and the description adds significant behavior: cursor pagination on stable (hostname, role) order, deliberate omission of the evidence blob, and detailed null semantics for staleness fields ('null is not zero', tracked vs untracked distinction). This goes well beyond what annotations provide and prepares the agent for surprising edge cases.

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 a one-sentence purpose, and most later sentences add necessary nuance about pagination, evidence omission, and null semantics. It is longer than necessary — the internal 'issue #798' reference and the unexplained 'Market tier' suffix are noise — but the detail earns its place 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 tool with no output schema, the description carries the return-format burden and does so thoroughly: row granularity, folded axes, omitted evidence, pagination, and exact empty/NULL semantics. With readOnlyHint true and all parameters documented, nothing essential to invoking the tool correctly 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?

All three parameters are already fully described in the schema (100% coverage), so the description has little additional parameter burden. It only restates the vendor filter as 'optional vendor= filter' and doesn't add syntax or semantics beyond the schema. 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 opens with a clear verb+object — 'List all hosts' software' — and precisely scopes the rows: one per (hostname, role), with vendor/version/hosting axes folded in. This distinguishes it from siblings like get_host_software or list_host_software_history even without naming them, because it defines the list's shape and scope.

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 frames the tool as a lean list: the evidence blob is intentionally omitted and stays on the per-host resource, implying that detailed evidence should be fetched elsewhere. It gives context for the cursor-paginated all-hosts use case and the optional vendor filter, but it does not explicitly name sibling alternatives or state when not to use it. That is clear context without hard 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?

Annotations already declare readOnlyHint=true, and the description adds useful behavior beyond that: the rows are closed/superseded, sorted newest-first, cursor-paginated, and each row represents one axis transition with evidence. This gives an agent meaningful context about what the call actually returns.

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 short and front-loaded, with the core purpose in the first sentence and useful behavioral details following. The only structural weakness is the abrupt 'Market tier.' fragment, which is underspecified but does not bloat the overall description.

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 description covers the essentials: one host, superseded rows, ordering, pagination, and row evidence. However, there is no output schema, and terms like 'axis transition' and 'Market tier' are vague enough that an agent may struggle to interpret the returned row contents.

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 each parameter already has a clear description: limit, cursor, and hostname. The tool description mostly reinforces the pagination and one-host scope but does not add materially new parameter-level meaning 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 starts with a specific verb and resource: 'List a host's software-fingerprint history,' and then clarifies that it returns closed/superseded rows for one host. This distinguishes it from current-state tools like get_host_software, though it leaves 'axis transition' undefined.

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 when to use the tool: when you need superseded software-fingerprint rows for a single host, newest-first. It does not explicitly name alternatives or state when not to use it, so the routing guidance is only implied rather than fully 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?

Annotations indicate readOnlyHint=true, and the description adds behavioral context by mentioning keyset-pagination on (scheme, value) and the presence of meta.facets on the first page. This goes beyond the annotation without over-explaining.

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 purpose, and every clause adds value. It avoids repetition of schema details and focuses on non-obvious behavior.

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 there is no output schema, the description explains the pagination approach and the meta.facets structure, which is useful. It doesn't detail the exact fields of each malformed identifier, but the phrase 'individual identifiers' gives a reasonable hint. Overall, it's complete enough for a list/filter tool with well-documented schema.

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 all parameters already have descriptions. The tool description does not add additional parameter semantics, but it implicitly relates cursor and limit to the pagination strategy, which is marginal value. 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 malformed participant identifiers, defines what those are ('identifiers that failed their scheme's structural rule'), and distinguishes it by introducing the pagination and facets. The verb 'list' and resource are specific, differentiating it from sibling tools like get_id_quality.

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 for use: it's for viewing malformed identifiers, with keyset pagination and facet counts for analysis. It does not explicitly state when not to use or name alternatives, but the context is strong enough that an agent can infer appropriate use cases.

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 readOnly annotation already signals safety, and the description adds useful behavioral details: global scope, newest-first ordering, and cursor pagination. This goes beyond the annotation and helps the agent understand the tool's operational behavior without needing to inspect schema details.

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, front-loading the purpose ('List incidents') and adding only essential qualifiers in a compact form. Every word earns its place, making it easy to parse quickly.

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 read-only annotation, complete schema, and simple list operation, the description provides adequate context for invocation: it names the global feed, ordering, and pagination. It does not describe the return structure, but since there is no output schema, this is a minor gap; overall, the tool is well contextualized.

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 covers all parameters thoroughly (100% coverage), so the description adds little parameter semantics. The description's 'newest-first' and 'cursor-paginated' align with the limit and cursor parameters, but these are also inferred from the schema, so no extra value beyond 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 clearly states the tool lists incidents, with specific qualifiers: global feed, newest-first, cursor-paginated. This distinguishes it from sibling list_host_incidents by emphasizing the global scope, making the purpose unambiguous.

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: it is the global incident feed, so the agent knows to use this for all incidents. It does not explicitly exclude alternatives or mention host-specific listing, but the 'global' qualifier alone implies the appropriate use case.

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 provide readOnlyHint=true, and the description adds useful behavioral details: events are 'newest-first' and 'cursor-paginated'. This goes beyond the annotation by specifying ordering and pagination style.

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: the first states the purpose, the second provides key behavioral details. No filler or 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 simple read-only list tool with well-described parameters and annotations, the description provides adequate context (ordering, pagination, scope). It could mention the response shape but 'change events' is sufficient for a list 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?

Schema descriptions cover 100% of parameters (id, limit, cursor) with clear meaning. The description adds little beyond referencing pagination (cursor-paginated), which is already implied by the schema's cursor 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?

The description clearly states the action ('List') and the specific resource ('a participant's change events'), which distinguishes it from sibling tools like get_participant_history or list_events. The additional phrase 'typed change events' further narrows the scope.

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 for participant change events but does not explicitly state when to use this tool versus alternatives such as list_events or get_participant. No exclusion or alternative guidance is provided.

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 carry readOnlyHint, so the description must disclose behavior. It does so thoroughly: keyset pagination, default sort order, the distinction between first-page meta totals and bounded filter_count that degrades to null, and the privacy caveat for discovered participants. No contradictions.

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 single, dense paragraph that front-loads the action and then packs high-value behavioral details. It avoids redundancy with the schema despite covering many filters. For a 26-parameter tool, the length is justified and does not meander.

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, the description partially compensates by describing pagination, meta, and privacy, but it does not enumerate the participant fields that will be returned (except noting discovered ones lack name/card). Given the tool's complexity, an agent would still need external knowledge of the participant representation.

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 100% of parameters, so baseline is 3. The description adds high-level grouping (comma-array filters, single-valued sub_provider, smart q) and call-outs like meta.filter_count, but most parameter specifics already live in the schema. It adds some interpretive value without being essential.

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 verb-resource pair ('List participants') and elaborates that it returns the participant set with pagination. It does not explicitly compare with siblings like get_participant or list_participant_events, but the name and scope are unambiguous.

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 for listing/filtering participants but never states when to prefer this over siblings like get_participant or list_participant_events. There is no explicit when-not or alternative routing, though the filter-heavy detail suggests it is for bulk enumeration. This is adequate but left to inference.

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 readOnlyHint annotation already signals a safe read operation, and the description adds valuable context about the specific content returned (per-Seat counts, expiries, identity shifts). It does not discuss pagination limits or error cases, but for a read-only aggregate tool this is 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?

The description is one well-formed sentence with a clear subject and a structured list of outputs. It packs substantial detail without redundancy, though the list is slightly long; still, each item earns its place.

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, the description carries the responsibility of explaining the return payload, and it does so thoroughly by listing all components (cert counts, expiry thresholds, organisations, identity shift). Given the tool's single-parameter simplicity and read-only nature, the description is sufficiently complete.

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 single parameter 'slug' is fully described in the schema as 'The curated provider slug', which makes the schema coverage 100%. The tool description adds no additional parameter-level detail, so it relies on the schema as the baseline.

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