Agent Service Directory

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?

Annotations only declare idempotent/not-read-only; the description goes well beyond them by disclosing the free API key requirement with the exact Bearer scheme and key-provisioning endpoint, plus that reports are stored as unverified claims and only published after moderation, and a data-hygiene prohibition on task data, secrets and PII.

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 purpose in the first clause, then layers prerequisites, provenance and prohibitions in a compact sequence of sentences. Auth endpoint detail is useful but slightly dense for the opening line.

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

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

A write tool with no output schema is well covered on auth, idempotency and data handling. It could still say what a successful or rejected report returns, and whether moderation blocks the caller, but the preconditions an agent needs are all 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 coverage is 71% and the enum values are self-documenting, so the baseline is 3. The description reinforces referral_id provenance and adds a hygiene rule relevant to task_category, but supplies no format or syntax detail the schema does not already carry.

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 with timing scoped to 'After using a service', so the agent knows exactly what is being recorded. It does not differentiate itself from the sibling send_feedback, which an agent could plausibly confuse with outcome reporting.

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 clear trigger context ('after using a service') and points at get_service as the source of the preferred identifier, so the agent knows the prerequisite flow. There is no explicit when-not guidance or comparison against send_feedback/get_report.

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 the safe read-only, closed-world profile, so the bar is lower. The description still adds useful behavior: every result carries evidence, results are compact, and limit/offset control paging — practical invocation context the 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?

Three tight sentences, front-loaded with what the tool finds, then filtering guidance, then the sibling handoff and paging hint. One borderline sentence ('Results are compact') earns its place by setting expectations for result size.

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, no-output-schema search tool, the description covers purpose, evidence filtering, the follow-up call, and pagination. It stops short of describing ranking defaults or the evidence fields returned per result, but the schema carries the remaining filter semantics at 73% coverage.

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 73% with self-documenting enum/range fields, so the baseline is 3. The description adds the relational semantics of the evidence filters (you filter on them and then pick), but does not clarify the many unmentioned filters (sort, tier, network, min_checks, one_per_provider, max_terms_changes_90d) beyond what the schema already says.

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') plus the organizing dimension ('by purpose, with evidence for each'). It also contrasts itself with the sibling get_service, which supplies connection details, so an agent can route between them without opening either 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 evidence fields (passing, min_pass_rate, max_price_usd), pick one, then call get_service. No explicit 'when not to use' or exclusions, but the follow-up handoff to get_service makes the intended sequence unambiguous.

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 annotations (readOnlyHint=false, idempotentHint=false), the description discloses genuinely useful behavior: no auth required, that counts by kind become public on the roadmap while messages stay private, and that sensitive data must never be included. This data-handling and visibility disclosure is real added value, though it says nothing about what a call returns or error 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?

A single tight paragraph: purpose first, then prerequisites, then data-handling caveats. Every sentence carries weight, with only mild redundancy between the enumerated kinds and the chained clauses.

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 4-parameter, one-required submission tool with no output schema, the description covers purpose, prerequisites, acceptable inputs, and privacy constraints. It leaves a small gap on what happens after submission (confirmation/return), but otherwise the agent has enough to call it correctly.

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

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

Schema coverage is 75% with self-documenting enum values for 'kind', and the description's category list maps closely to that enum without adding much beyond it. The note/about/contact parameters are explained in the schema itself, so the description neither compensates nor detracts; 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 opening clause states a specific action (submit feedback) and enumerates exactly what qualifies: missing services, metrics, features, wrong data, unclear docs. This is clearly a write/submission tool and cannot be confused with its read-only siblings (get_*, search_services). It stops short of explicitly naming any sibling, so it lands at 4 rather than 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?

'No key needed' and 'we use it to decide where to look next' tell the agent the context and prerequisites for calling it. The list of acceptable feedback kinds implicitly bounds when to use it, but no alternative or when-not-to-use guidance is given.

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