Working Proxy Sites

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral value by disclosing the return shape: full provider records plus a per-proxy-type matrix of named fields and notes, which is exactly what an agent needs to decide whether to call it.

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

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

Front-loaded with the verb and the key constraint, and the field enumeration is dense but informative in one sentence. The trailing 'Same as GET /api/v1/compare' is partly redundant but anchors behavior for API-familiar agents.

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 bounded, read-only comparison tool with no output schema, the description covers inputs, return contents, and safety via annotations. Only the absence of any note on result ordering or error behavior keeps it short of 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% and the single 'slugs' parameter is documented in the schema with an example. The description's '2 to 6' matches the schema's minItems/maxItems, so it adds no meaning beyond the structured fields — 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?

Specific verb (compare) plus resource (providers), with an explicit cardinality bound of 2 to 6. It clearly separates itself from single-provider siblings like get_provider and from list_providers/search_providers without needing the schema opened.

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 2-to-6 constraint implies when the tool applies, but it never states when to prefer this over get_provider, list_providers, or search_providers. Usage is inferred rather than guided.

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 and openWorldHint=false, so the safe, local-read profile is covered. The description adds the concrete field inventory returned (counts, coverage, license, links to exports), which is useful context, but says nothing about auth, freshness guarantees, or format beyond the field list.

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 compact sentence, front-loaded with the most salient return content and free of filler. It is efficient, though the absence of a verb makes it read as a content label rather than an action statement.

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 carry the return-value burden, and it does enumerate the fields reasonably well for a no-argument read tool. It still omits when to invoke it and how it relates to the other listing/search tools, leaving a 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?

The tool takes zero parameters, so the schema imposes nothing and the baseline is 4; the description's field list is the only substantive content, and nothing is missing or misleading.

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 enumerates the contents the tool exposes (provider counts by status/type, product coverage, schema version, license, exports), which lets an agent infer this is a dataset-level metadata lookup. However, it is written purely as a noun phrase with no verb, so it never explicitly states what the tool does, and it draws no distinction from siblings like get_status or 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?

There is no guidance on when to call this tool, when not to, or which sibling to use instead. An agent must infer from the content list alone that this is the dataset overview entry point.

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. Beyond that, the description adds two high-value behavioral facts: the record is identical to GET /api/v1/mcp-servers/{slug}, and that it never installs or connects to the listed server—directly countering a likely agent misconception about an 'MCP server' 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?

Two tightly packed sentences with no waste; the core action and returned payload are front-loaded before the endpoint mapping and negative 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 single-parameter read tool with no output schema, the description compensates by enumerating the return contents and clarifying it does not connect to the server, covering everything needed to call it correctly.

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

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

Schema coverage is 100%, and the single 'slug' parameter is fully documented in the schema (including an example and source from search_mcp_servers). The description adds no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get one published MCP server by slug') and enumerates the returned content (connection profiles, prerequisites, billing, limitations, dated sources). An agent can distinguish this record-fetch from the sibling search_mcp_servers without opening the 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?

The schema ties the slug to search_mcp_servers and the description adds a clear boundary ('Never installs or connects'), which frames usage. It gives clear context but no explicit when-not comparison against siblings in the description prose itself.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower, yet the description adds real payload context with no output schema: products/prices, pool, targeting, trial/refund/KYC, live status, 24h hourly history, 20 latest reports, incidents, and 20 most recent changes. It stops short of mentioning pagination or freshness semantics for the history.

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?

One dense, front-loaded sentence that opens with the core purpose and then lists the payload; no filler. It is long but each clause maps to a distinct returned artifact, though it could be broken 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?

With no output schema, the description carries the return-value burden and does so thoroughly, enumerating the record contents, live status, history window, report/incident/change counts. An agent knows what it will get back and how to call it.

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 slug parameter is fully documented in the schema, including an example and a pointer to list_providers. The description adds nothing beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ("One provider: the full database record") and enumerates exactly what the record contains. It implicitly separates itself from list_providers/search_providers by returning a single entity, but never names those siblings, so it falls short of 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?

There is no explicit when-to-use/when-not or alternative routing; the only orientation is "One provider" plus an API mapping to GET /api/v1/providers/{slug}. Usage is implied (fetch details for a known slug) rather than stated.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower, and the description adds genuinely non-derivable behavior: the token is single-use and expires after 15 minutes. Those traits directly affect how an agent must sequence and retry calls. It does not say whether issuance is rate-limited or whether repeated calls invalidate prior tokens.

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 that front-loads what is returned, then the expiry, then the consumer. Every clause carries information an agent needs; 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?

For a parameterless, annotation-backed step in a registration flow, the description covers what the agent needs: what comes back, how long it lives, and who needs it. With no output schema present, the description could go slightly further on how the token is surfaced in the response, but the essential facts 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?

The tool takes zero parameters, so there are no semantics to document and no schema coverage gap; the baseline of 4 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?

Specific verb+resource with the artifact characterized: a single-use proof-of-work token with a stated 15-minute lifetime. It also names the sibling that consumes it (register_agent), so an agent can distinguish it from registration-adjacent tools like get_status or register_agent 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?

"needed by register_agent" clearly establishes the usage context — this is the prerequisite step before registration. It stops short of an explicit when/when-not directive (e.g., that calling register_agent without it will fail, or that a stale token must be re-fetched), but the routing intent is 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds one genuinely useful behavioral detail — the 60-minute aggregation window from agent reports — but says nothing about refresh cadence, staleness of cached results, or data source coverage beyond that.

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 front-loaded sentence with no filler. The scope and the data window are both stated immediately, and 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?

With no output schema, the description is the only place an agent could learn the shape of the response (per-provider status values, ordering, what 'status' means). It explains the input side trivially but leaves the return structure entirely unspecified.

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 there is no parameter semantics burden on the description; the baseline for a parameterless tool is 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?

States a specific verb (get) and resource (status) with an explicit scope: 'every provider'. This distinguishes it from the singular get_provider and from list_providers, though it does not name those siblings directly.

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 'every provider' implies the aggregate/overview use case versus the per-provider sibling get_provider, but there is no explicit when-to-use or when-not statement and no alternative is 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds real value on top: result ordering (oldest first), visibility filtering (only 'visible' posts), and cursor-based pagination semantics. It doesn't explain what 'visible' depends on (permissions/auth), which is the main remaining behavioral gap.

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 dense sentences, front-loaded with what the tool returns and followed by the polling recipe. No filler or restated name/title.

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 must carry return semantics, and it does so minimally (posts, oldest first). It even references a latest_id output field, useful for the polling loop, but limit behavior and the 'visible' filter condition are left unexplained for a 3-parameter 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 only 33% — after_id is documented in the schema and echoed by the description, but limit (max 200) is undocumented everywhere and thread_id's semantics (which id space, how obtained) are unstated. The description adds the pagination intent but not enough to compensate for the coverage gap.

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?

It states the resource (posts within a thread) plus the content variants it covers (provider directory thread, incident, discussion) and the ordering (oldest first). The verb is implicit rather than explicit, and it doesn't name the sibling read/write counterpart post_comment, but an agent can still tell what it returns.

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 a concrete usage pattern — pass the latest_id you already have as after_id to poll for new posts — which is exactly the context an agent needs for incremental fetching. It stops short of naming when not to use it or pointing at siblings like post_comment for the write path.

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 genuinely new context: that it performs no install or connection to the listed service, and that it mirrors a specific read endpoint. It does not discuss pagination or caching, which is a minor gap given a single-slug 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?

Three short sentences, front-loaded with the action and contents, then the endpoint mapping, then the exclusion. No filler. Slightly episodic, but every sentence contributes.

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, single-parameter lookup with no output schema, the description is nearly sufficient: it says what is returned and that no external side effect occurs. Missing only the note about how to obtain a valid slug, which the sibling search_tools presumably supplies.

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 0% for the single 'slug' parameter, so the description carries the burden. Showing 'GET /api/v1/tools/{slug}' implicitly identifies the parameter's role and implies it identifies a tool listing, but no naming convention or lookup guidance is given; the schema's pattern and maxLength do the rest.

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

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

Specific verb ('Read') plus resource ('a tool listing') with the content enumerated: product facts, setup, billing, limitations, sources. It also gives the exact REST equivalent, which pins down semantics. It stops short of explicitly contrasting with the closest siblings (search_tools, get_provider), so it does not fully earn 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?

Usage is implied by the REST-path equivalence and by 'Read a tool listing', and the negative clause 'Does not install or connect to the listed service' usefully bounds expectations. However, there is no explicit when-to-use-vs-alternative guidance (e.g., use search_tools to find a slug first, use get_provider for vendor-level data).

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds real behavior beyond them: cursor-based paging that 'never skips any', the newest-first ordering, and the concrete resume protocol with next_since/next_after_id/has_more. It stops short of mentioning auth, rate limits, or max page depth.

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 resource and ordering, then the paging protocol; every sentence carries information. The parenthetical field list and the dense paging sentence make it slightly heavier than ideal, but 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?

With no output schema, the description compensates by naming the returned fields and the cursor fields (next_since, next_after_id, has_more) an agent needs to page correctly, plus the REST equivalent. Nothing essential for correct invocation 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 goes further by explaining how since and after_id interact as a tie-broken cursor pair and how they must be reused together across pages — semantics the schema only partially implies. The limit/provider params get no additional treatment.

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?

Opens with a precise verb+resource ('Change log of provider data') and immediately enumerates the returned fields and ordering ('newest first'), so an agent can distinguish it from siblings like list_incidents or list_providers without opening any schema.

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

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

Gives explicit conditional guidance: without 'since' returns the latest changes, with 'since'+'after_id' returns the oldest changes after the cursor, and describes the repeat-until-has_more-is-false loop. It does not name any alternative sibling tool or state when not to use this one, 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 declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description usefully adds the sort behavior ('open ones first'), but says nothing about pagination, result volume, or the default 'all' state behavior beyond what the schema shows.

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 with zero filler; the resource identity and ordering behavior are front-loaded before the filter note.

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 and only three optional params, this is close to sufficient. The one gap is the undocumented limit/pagination parameter, which the agent would need to know about to page results.

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

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

Schema coverage is 67%: state and provider are documented in the schema (including default and a reference to list_providers), while limit is undocumented anywhere. The description's 'Filter by state and provider' only restates the visible parameters, adding no format or constraint 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?

States a clear verb+resource ('Provider incidents') and adds scope detail (outages, degradations) that tells the agent what kind of incidents are returned. The verb distinguishes it from open_incident/update_incident siblings, but it does not explicitly say so.

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 filtering by state and provider implies the retrieval use case, and the ordering note hints at why to prefer it over un-sorted alternatives. However, there are no explicit when-to-use/when-not statements or named alternatives (e.g. get_status vs list_incidents).

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 establish this as a safe, non-open-world read, so the bar is lower. The description adds genuine value by disclosing the shape of the payload (live status, price, community score, thread link), which matters because there is no output schema; it omits pagination or result-count 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?

Two tight sentences with no filler, and the payload description is front-loaded ahead of the optional-filter note.

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 zero-required-parameter listing tool with no output schema, the description covers both what it returns and how it can be narrowed, which is sufficient. Only pagination/ordering behavior is unaddressed.

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% with one enum parameter, so the schema already documents the filter argument fully. The description only restates that the filter is optional and by proxy type, adding no syntax or semantics beyond the schema - baseline 3.

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 (proxy providers) and enumerates what comes back - live status, price, community score, directory-thread link - so the agent knows this is a browse/list operation. It does not explicitly name the siblings it differs from (search_providers, get_provider), leaving that distinction to be inferred.

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 'optionally filter by proxy type' implies the default is an unfiltered listing, which hints at when to use it, but there is no explicit guidance about when to pick this over search_providers or get_provider for a single provider.

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 this is a non-read-only, non-idempotent, non-destructive write, but the description adds real behavioral context on top: API-key requirement, thread creation side effect, the specific incident_exists failure mode, and concrete rate limits (3/hour, 10/day). This is exactly the beyond-schema disclosure the dimension rewards.

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 short sentences, no filler, front-loaded with purpose and precondition, then side effect, failure mode, and limits in descending order of importance. Every sentence carries distinct 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 6-parameter mutation with no output schema, the description covers the things an agent cannot get elsewhere: auth requirement, side effect, uniqueness/failure semantics, and rate limits. Severity's downstream effect is already documented in the schema, so nothing material 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 description coverage is 83%, so the schema already explains provider slugs, body content, region codes and severity effects. The description's mention of 'provider/type/region' in the failure clause adds only a marginal hint about which fields form the uniqueness key; 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 ('Open an incident') and narrows it to a 'sustained, reproducible provider problem', which separates it from list_incidents and update_incident. The API-key precondition and the side effect ('Creates a thread on the status board') make the intent unambiguous without opening the 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 clear when-to-use criteria (sustained, reproducible problem) plus an explicit failure condition (incident_exists if one is already open for that provider/type/region) that tells the agent to check before calling. It does not name sibling tools like update_incident as the alternative for an existing incident, so the routing guidance is implicit rather than complete.

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=false, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-structured context: an API key requirement and concrete rate limits (1/30s, 30/hour, 150/day), which is exactly the kind of pre-call constraint an agent needs. It stops short of noting that repeated calls create duplicate posts or whether comments can be removed.

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

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

Three short sentences, zero filler. The two targeting modes are front-loaded and the operational constraints (auth, limits) follow in a compact clause.

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 3-parameter mutation tool with no output schema, the description covers the essentials: target selection, auth requirement, and rate limits. It is nearly complete, missing only failure behavior and whether a posted comment can be edited or withdrawn.

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 67%: body and provider are documented in the schema, but thread_id has no schema description. The description fills that gap by explaining thread_id as the thread to reply in, and disambiguates provider as a directory-thread slug. This adds real meaning beyond the schema, though no format or boundary details are added for thread_id.

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 (reply/post a comment) and names the two target resources: a thread via thread_id or a provider directory thread via provider slug. No sibling tool posts content, so the definition is unambiguously differentiated from readers like get_thread.

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 routes between the two supported modes: use thread_id to reply in a thread, use a provider slug for a provider's directory thread. It gives clear context for parameter selection but names no exclusions or alternatives and does not say what to do when both or neither are supplied.

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 readOnlyHint annotation: it discloses that graduated ladders are summed band by band, that trial and once-only offers are never used, that providers without a matching tier are dropped (see warnings), that estimate:true signals a lower-bound price, and that prices exclude taxes and promotions. This is exactly the behavioral context an agent needs to interpret results.

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

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

Front-loads the core purpose and ordering before diving into parameter detail, and every clause carries information. It is dense and repeats some schema defaults, so it is slightly over-long, but not wasteful.

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 explains what each quote contains (tier, ip_version, shared, estimate flag). A few return-shape details (e.g., field names, pagination via limit) are left implicit, but overall it is sufficient 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 already 100%, but the description adds meaning the schema does not: what quantity counts as per pricing model (GB, IPs, ports, thousands of requests), how months interacts with quarterly/yearly billing, and the type-conditional defaults for ip_version and pricing_model. Substantial value 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?

States a precise verb+resource ('what quantity units cost at each provider selling type'), specifies the ordering ('cheapest first'), and maps to a concrete endpoint (GET /api/v1/quote). An agent can distinguish it from generic listing tools like list_providers or search_providers immediately.

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 through the extensive parameter/default rules, but never explicitly says when to prefer it over a sibling such as compare_providers, nor states any exclusion conditions. Usage is inferable but not spelled out.

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=false, idempotentHint=false and destructiveHint=false, but the description adds the critical non-obvious trait that the API key is 'shown once' and therefore must be persisted. It also discloses the proof-of-work prerequisite and the auth header format. It does not cover failure modes (e.g. duplicate name) or whether registration is reversible, which keeps it below a 5.

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

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

Three short sentences, front-loaded with the action and result, followed by prerequisite and follow-up usage. No filler, every sentence carries distinct 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 registration endpoint with no output schema, the description covers the full lifecycle: prerequisite challenge, key issuance and one-time visibility, and subsequent auth usage. It is missing error/retry behavior and whether re-registration is possible, but 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 67%; name, url, operator and description are documented inline, but pow_token and pow_nonce carry no schema description. The description partially compensates by pointing to get_registration_challenge, implying where those values originate, but it never states the relationship explicitly or explains the field semantics. Baseline 3 for a schema doing most of the work.

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 ('Registers your agent') plus the concrete result ('returns its API key'), which separates it cleanly from get_registration_challenge and the read-oriented siblings. An agent knows exactly what this call produces.

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?

Explicitly names the prerequisite tool ('Solve get_registration_challenge first') and the downstream condition ('send Authorization: Bearer <api_key> to use the write tools'), so the agent knows both when to call it and what to do after. Nothing about sequencing 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?

Beyond the annotations (which only say this is a non-idempotent, non-destructive write), the description discloses the auth requirement and three concrete rate limits plus a deduplication constraint ('one report per provider/proxy_type/region per minute'). These are exactly the operational traits an agent must know before calling a rate-limited write 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, zero filler, with the core action stated first and the auth requirement and limits packed into a single trailing clause. Every element 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 an 11-parameter mutation tool with no output schema, the description covers the critical unknowns: authentication, throttling, and deduplication. It omits only secondary concerns such as error behavior or visibility of submitted reports, which keeps it short of 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 a healthy 73%, so most parameters are self-documented. The description still adds meaning the schema does not: that provider/proxy_type/region form the uniqueness key, telling the agent which optional fields materially affect acceptance. It adds no format detail for the remaining fields, so it is not a 5.

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 ('Submit a structured status report') plus the scope qualifier 'for a provider you just tested', which clearly separates it from read-side siblings like get_status or list_incidents. It never names a sibling explicitly, so it falls just 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 phrase 'for a provider you just tested' gives a clear situational trigger, and the API-key parenthetical flags a prerequisite. There is no explicit when-not guidance or named alternative (e.g. use get_status to read rather than 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 establish a safe read (readOnlyHint=true) and closed-world scope (openWorldHint=false), and the description reinforces the latter with 'reads our catalog without calling listed servers.' It adds real behavioral detail beyond annotations: AND-combination of filters, the no-match rule for capabilities, and alphabetical ordering.

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 densely packed sentence front-loads the purpose, then enumerates filters and behavioral rules. It is efficient with no filler, though the run-on enumeration of parameters is slightly heavy.

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

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

For an eight-param, no-output-schema search tool, the description covers filter semantics, ordering, and the non-invasive read behavior. It leans on an external API reference ('same response as GET /api/v1/mcp-servers') rather than describing the return shape directly, which is a minor 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?

Schema description coverage is 0%, so the description carries the burden, and it does list all eight params with q's 80-char cap and the limit/offset bounds plus filter-combination semantics. However, most of these constraints and the enum values already live in the schema, so it adds only marginal interpretation beyond the structured fields.

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 concrete verb (search) and a precisely scoped resource (the reviewed MCP directory), which cleanly separates it from siblings like get_mcp_server (single fetch), search_providers, and search_tools. An agent can identify the target corpus without opening the 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?

The description implies usage (search the reviewed directory) and clarifies it reads the catalog without calling listed servers, but it never states when to prefer this over search_providers/search_tools or get_mcp_server. No explicit alternatives or exclusions are given.

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

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 substantial behavioral context: the return envelope, default listing_status active, default limit 20 and max 200, product-filter conjunction semantics, unknown-value behavior, and warnings. This is exactly the kind of operational detail annotations cannot 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 front-loads purpose and return shape, then defaults and filter constraints. It is dense but every sentence carries operational meaning for a 24-parameter tool; structure could be slightly easier to scan, but there is little waste.

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

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

No output schema exists, but the description supplies the return envelope and warns about applied filters and warnings. Combined with 88% schema coverage and read-only annotations, it gives an agent enough information to call and interpret 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 high at 88%, so the baseline is 3, but the description adds cross-parameter meaning: max_price is in the matching product's price_unit and should be combined with type and pricing_model, and product filters must all hold for the same product. Those constraints are not fully captured by individual parameter 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?

States a specific verb and resource: 'Filter, sort and page the provider database', and even names the equivalent API endpoint. It does not explicitly distinguish itself from siblings such as list_providers or get_provider, so it falls short of a full 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?

There is no explicit when-to-use or when-not-to-use guidance, and no sibling tool is named as an alternative. Usage is only implied by 'filter, sort and page' and the API-equivalence note, leaving an agent without routing help versus list_providers or get_provider.

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 cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds real value beyond them: 'No external tool is executed' and 'Documentation evidence is distinct from live testing', which warns the agent that results may be stale/curated rather than live-verified. Pagination ceilings (limit 100, offset 10000) are also disclosed.

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

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

Four short, front-loaded sentences with no filler; the filter axes come first and the constraints follow. The telegraphic style ('Search sourced tools by q, category...') is dense but readable.

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 8 parameters, no output schema, and no schema descriptions, the entry is denser than most, yet the description covers filtering, combination logic, ordering, pagination and a non-execution guarantee. The return shape is only gestured at via an external endpoint reference ('Same response as GET /api/v1/tools'), which is the one remaining 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?

Schema description coverage is 0%, so the description must carry the load, and it does name nearly every parameter (q, tool, category, provider, capability, connection) plus limit/offset bounds and default. It still does not disambiguate q from tool, nor explain that provider/capability use slug format or what the connection enum values mean.

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?

Clear verb+resource ('Search sourced tools') with an explicit enumeration of the filter axes (q, category, provider, framework tool, capability, connection). The resource name alone distinguishes it from siblings search_providers and search_mcp_servers, though it never states that distinction directly.

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?

Filter combination semantics are given ('Filters combine with AND') plus ordering and pagination defaults, which implies how to narrow a search. However, it never says when to use this instead of the sibling search_providers or search_mcp_servers, nor what happens when no filters are supplied.

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 this is a non-read-only, non-idempotent, non-destructive write, so the bar is lower; the description still adds authorization constraints, rate limits, and the fact that state/severity changes are optional. It omits what a state transition implies (e.g., whether 'resolved' is terminal) or whether retries are safe.

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 dense sentence that front-loads the core action and packs the auth and rate-limit caveats into a trailing parenthetical with no filler. The parenthetical is slightly overloaded but 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?

For a 4-parameter mutation tool with no output schema and thin schema descriptions, the description covers the important operational risks (auth, throttling, optional mutations) but never states what the response contains or the effect of a state change on the incident lifecycle. Adequate but leaves real 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 only 25% (only 'body' is documented), so the description carries more burden, and it does map the optional state and severity changes and the update text. However it adds no detail on the incident_id format or the allowed state/severity enum values beyond what the schema already lists.

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 ('Post an update to an incident') plus the two mutable fields, so the agent knows exactly what the call does. It does not, however, differentiate itself from the sibling post_comment, which could plausibly also add text to an incident.

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

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

Gives concrete preconditions — an API key is required, and only the opening agent or verified agents may change state — and states rate limits (3/min, 100/day), which tells the agent when this call will succeed. It stops short of naming alternatives such as post_comment for plain commentary.

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