Agent Service Atlas

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine domain context with 'pending interpretation, not necessarily a breaking change,' which steers interpretation of results, but it says nothing about time-window defaults, pagination, or result volume.

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 compact sentences, with the resource and scope front-loaded and the semantic caveat second. Nothing is wasted, though 'recently' is left vague when a concrete default window is available to state.

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 two-parameter read-only tool with no output schema and no nested objects, the description covers scope, filtering intent, and the nature of the returned data. It is close to complete, with only the trigger to use it over get_history left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (id, days) are already documented in the schema; baseline 3 applies. The description's 'or for one' loosely reinforces the id filter but adds no format or semantics beyond what the schema supplies, and never mentions the days window.

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 clear resource (recently detected changes) and its scope (monitored documentation and API schemas across all reviewed services or one), plus a definition of what a 'detected change' means. It does not name or contrast with any sibling such as get_history, so the agent must infer the boundary between current changes and historical ones.

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 'across all reviewed services or for one' implies the optional id filter, and 'pending interpretation' hints at the state of results. However, there is no explicit when-to-use guidance, no exclusion vs get_history/get_report, and no stated prerequisite for interpreting the results.

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 the ordering ('newest first') and the use case, which is useful context beyond annotations. Annotations cover the safety profile (readOnlyHint=true, openWorldHint=false). However, the description does not mention pagination behavior (limit parameter handling), rate limits, or whether all historical data is retained beyond the days parameter. With annotations covering safety, this is adequate but not rich.

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

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

Two sentences, front-loaded with the core output description and then the usage guidance. No wasted words; 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?

Given the absence of an output schema, the description should explain what the return values contain beyond the ordering. It mentions 'individual check results' and 'patterns' but does not specify the fields or structure of a check result. For a tool that returns potentially large datasets, more detail on pagination or result shape would be helpful. The annotations cover the safety profile, and the description is adequate but leaves gaps for an agent to confidently call it 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?

Schema description coverage is 67%, with 'days' and 'limit' having descriptions ('Default 7.' and 'Default 50.'). The description does not add any parameter details beyond what is in the schema. Baseline 3 is appropriate when schema provides partial 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 returns 'individual check results for a service over the last days, newest first', which is a specific verb+resource and indicates the ordering. It does not explicitly differentiate from sibling tools like get_report or get_stats, but the specificity of 'individual check results' helps the agent understand it's a detailed drill-down.

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: 'Use it to see patterns (intermittent failures, slowdowns) behind the summary figures.' This implies when to use it versus summary tools like get_report or get_stats, though it does not name those alternatives explicitly or state 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds substantive context beyond them: results are aggregates only ('counts and distributions only, with their method') and 'current' figures are provisional week-to-date, a data-freshness caveat the annotations do not convey. It stops short of describing pagination or output volume.

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

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

Purpose and scope are front-loaded in the first sentence, with parameter-mode guidance following. It is dense and largely waste-free, though the middle clause ('Counts and distributions only, with their method') is slightly clipped in phrasing.

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

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

For a single optional parameter with no output schema, the description adequately covers what the report contains and how to select the latest versus provisional version. It could say a bit more about scope boundaries versus the stats/history siblings, but nothing essential for a correct call is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema cannot express: the absent-id default (latest published report) and the distinction between a final dated report and the provisional 'current' mode. That is real added value over the pattern 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?

States a specific verb+resource ('weekly State of Agent Services report') and enumerates the covered domains (coverage, probe results, payment networks, prices, purpose tags), which implicitly separates it from siblings like get_stats or get_changes. It never names a sibling explicitly, so it falls short of the 5 bar for full 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 gives mode-selection guidance for the id parameter (omit for latest published, 'current' for provisional week-to-date), which is genuinely useful. However, it never states when to prefer this tool over alternatives such as get_stats or get_history, so selection versus siblings is 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?

Annotations mark this as non-read-only, non-idempotent and closed-world, and the description supplies the reason implicitly by revealing that a referral_id is minted and consumed by report_outcome. The 7-day expiry is useful behavioral context the annotations cannot express; it stops short of explaining what happens on expiry or re-calls.

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

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

Two short sentences, zero filler, with the return payload front-loaded and the follow-up action second. Every clause 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?

No output schema exists, and the description sketches the response contents (evidence, connection details, referral_id) plus the required next step, which is enough for a 1-param lookup. Minor gaps remain around failure modes when the id is unknown or the referral has expired.

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 single 'id' param already documents the 'svc_...'/'cand_...' formats, so the schema carries the load. The description adds no additional parameter meaning, which is the expected baseline when coverage is this high.

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_service' → full evidence and connection details for one service) and discloses an extra return element, the referral_id. It is clearly distinct from the search_services sibling referenced in the schema, though no sibling is named in the description itself.

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

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

Gives explicit downstream workflow: take the referral_id to report_outcome after using the service, with a stated 7-day validity window. It does not explicitly state when to prefer this over get_report or get_history, so it stops short of full when/when-not 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact the annotations do not convey: the window is fixed at the last 24 hours, meaning the metric cannot be re-scoped. It does not say whether results are cached, when they refresh, or what the return shape looks like.

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?

A single sentence with no filler, and the time window is front-and-center rather than buried. It is efficient, though the noun-phrase phrasing (no leading verb) slightly softens the front-loading compared to a 'Returns X' construction.

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 summary tool with annotations covering safety and no output schema, the description supplies the essential content: which two numbers come back and over what period. What remains absent — refresh/caching behavior and precision of the counts — is minor 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 tool takes zero parameters, so the baseline of 4 applies; there are no parameter semantics to explain or miss. The description correctly implies the tool is parameterless by presenting the figures as fixed facts rather than as queryable dimensions.

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 two concrete metrics returned — the count of tracked services and the count of checks in the last 24 hours — so an agent knows exactly what this tool produces. It is clearly distinct from get_service (single entity), get_history/get_changes (event streams), and get_report (reports), though it never explicitly names those siblings to draw the boundary.

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 when-to-use or when-not-to-use statement and no alternative is named. An agent must infer that this is the entry point for summary counts rather than consulting get_report or get_history, and nothing clarifies whether this is a good first call or a last resort.

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

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

Goes well beyond the annotations: it discloses the auth requirement and how to obtain a key, that submissions are stored as unverified claims and only published after moderation, and an explicit privacy constraint. It also reinforces the idempotentHint with retry-safety context (retries with the same key are not counted twice), which the annotation alone only implies.

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

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

Front-loads the core action in the first clause, then packs auth, sourcing, moderation, and privacy into two tight sentences. Dense but no filler; the parenthetical key URL is the only heavy element and it 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 write tool with no output schema, it covers everything an agent needs: auth acquisition, the preferred identifier source, moderation semantics, idempotency behavior, and privacy limits. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Coverage is 71%, below the 80% bar, and the description only reinforces referral_id sourcing (already in the schema) while saying nothing about outcome, failure_kind, operation, or task_category semantics. Baseline 3 is appropriate since the schema carries most parameter meaning.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action and resource: report whether a used service worked. It is plainly the only write/submission tool among siblings that are all get_*/search_* readers, so an agent can distinguish it without opening a schema.

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

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

Gives a clear trigger ('after using a service') and ties to the sibling that produces the key input ('Quote the referral_id from get_service'), plus a clear exclusion (never include task data, secrets, or PI). It stops short of saying when NOT to report or what the alternative is if there is no referral_id beyond the schema hint.

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 openWorldHint=false, so safety and boundedness are covered. The description adds genuinely useful context beyond that: results carry evidence per service, they are compact, and pagination is via limit/offset. It does not describe the full result shape, but no contradiction with annotations exists.

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, front-loaded with purpose, then workflow, then paging. Each sentence earns its place, though the parenthetical filter list is slightly dense and the paging note could be merged.

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 15-parameter search tool with no required args and no output schema, the description covers purpose, the key evidence filters, the downstream step, and paging. It stops short of characterizing the returned record structure, but the workflow an agent needs to call it correctly is present.

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 73%, so the schema already documents most parameters, including the three filters the description names (passing, min_pass_rate, max_price_usd). The description adds only a framing hint ('filter on the evidence') and no 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?

States a specific verb and resource: 'Find payable APIs and agent task marketplaces by purpose, with evidence for each.' It also scopes the result set and points to the sibling (get_service) that consumes this tool's output, so an agent can place it in the family without opening a schema.

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

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

Gives a clear workflow: filter on the evidence fields, pick one, then call get_service for connection details. It tells the agent how this tool fits before and after, but offers no explicit when-not-to-use guidance or alternatives for narrowing a search (e.g. tag vs query).

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