Toolweather

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

Goes well beyond the readOnly/idempotent annotations by disclosing that it does not contact remotes, never spends a live-check credit, that each name consumes one Toolweather quota call, that an over-quota batch becomes a single $0.01 x402 charge, that unknown names yield verdict 'unknown', and what the response contains. This is exactly the billing and side-effect context an agent needs before batching.

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

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

Front-loaded with the core purpose, then constraints, then cost model, then return shape — four tight sentences with no filler. Every sentence carries information the agent would otherwise have to guess.

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 return fields (summary, checked_at, results[] verdict fields) and the unknown-name behavior. Combined with the billing and no-network disclosure, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds quota-cost meaning beyond the schema: each entry counts as one daily call, and unknown names return verdict unknown. It does not add format examples for the URL form, which keeps it short of 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 ('Read stored health verdicts'), quantifies scope ('up to 25 MCP servers'), and explicitly distinguishes itself from check_mcp_server_health and find_alternative_mcp_servers. An agent can tell exactly what this returns 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 an explicit when ('use at startup to vet that list') and two explicit when-nots with the correct alternative named for each (live handshake/auth detail → check_mcp_server_health; capability discovery → find_alternative_mcp_servers). Nothing 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 already cover readOnly/idempotent/non-destructive, so the bar is lower, but the description still adds real context: it does not invoke the provider's API, it enumerates the returned fields, states data freshness (~4 min), and discloses the billing path (Upstream quota, then $0.003 via x402). That is meaningful beyond the annotations.

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

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

Front-loads purpose, then usage, then exclusions, then return/pricing, so an agent can stop reading early. It is dense but avoids filler; the pricing and alias sentences are the only slightly extraneous weight.

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 return payload (summary, verdict, recommended_action, incidents, components, checked_at, freshness) and covering cost and the alias 'get_status'. An agent has everything needed to call and interpret 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 schema already explains the lowercase id format, that it comes from list_providers, and that it is not a URL; the description largely restates this. Baseline 3 is appropriate since the schema carries the 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 verb and resource ('Read whether one tracked AI or developer API provider is operational, degraded, or down') and immediately demarcates itself from check_mcp_server_health and check_model_deprecation. An agent can route correctly without opening a sibling 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 trigger conditions ('before calling that provider, or right after 5xx, 429, or timeouts'), explicit exclusions with the alternative tool named for each excluded case, and the correct id source (list_providers, not URLs). Nothing 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 already declare readOnly/idempotent/non-destructive, but the description adds behavior annotations don't cover: the 5-minute cache threshold, that stale/fresh/bearer_token triggers a live read-only initialize, the 200/day live-check budget falling back to cache, and the Toolweather quota (1,000/key or 50/day anon). This is unusually rich quota, caching, and auth-handling disclosure.

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

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

Front-loaded with purpose, then usage, exclusions, behavior, and returns; every sentence carries information. The enumerated return fields and alias mention border on density, but since there is no output schema they are justified rather than 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 compensates by listing the full return surface (verdict, recommended_action, reasons, latency_ms, auth, last_tool_change, checked_at, freshness). Combined with quota/caching notes and the sibling routing, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters (including tool, fresh, server matching rules, and bearer_token scope). The description restates the fresh/bearer_token live-check behavior but adds no parameter detail the schema lacks, 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 (read) and resource (one remote MCP server, optionally one tool) plus the exact scope: 'safe to call right now.' It explicitly distinguishes itself from siblings (find_alternative_mcp_servers, batch_check_mcp_servers, watch_server), so an agent can differentiate 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 trigger conditions ('before adding or calling that server, or after its calls fail or time out') and explicit exclusions naming the correct alternative for each ('Do not use it to search by capability... to vet a list... or to subscribe to later outages'). Nothing 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?

Adds a lot beyond the annotations: no transaction signing or key custody, the trusted allowlist is limited to published AI/dev APIs on port 443, wallets are never trusted, embedded 0x addresses score the host only, the 60-second idempotency window that does not consume a second check, and the exact quota/price model. The only gap is that it never says what the response body looks like beyond the four verdict strings, but with no output schema that remains acceptable.

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

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

Front-loads the purpose and verdict vocabulary, and most sentences carry non-obvious rules. It is dense but structurally sound; the api_key namespace clarification and the amount/category 'ignored' note are each stated twice (once in the description, once in the schema), which is mild redundancy.

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

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

With no output schema, the description supplies the return vocabulary and its meaning (trusted = published allowlist only, never a new domain or wallet), plus billing, quota, idempotency, and auth expectations. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100% so the baseline is 3, and the description earns above that by clarifying that amount_usd and category are inert ('changing them does not change the verdict'), the 40-hex-character address format, and the pc_live_ vs tw_ vs sg_live_ key namespaces. Some of this duplicates the schema text, so it is additive rather than essential.

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

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

Names a specific decision ('decide whether an autonomous agent should pay'), the resources it applies to (merchant, host, wallet), and enumerates the exact return values (trusted, unknown, suspicious, block). It explicitly separates itself from score_spend and paycheck_get_quota, so an agent can disambiguate 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 concrete trigger ('immediately before a payment, a checkout redirect, or a transfer to a new 0x address') and explicit exclusions ('Do not use it to send money, to score a dollar amount (score_spend), or to read remaining checks (paycheck_get_quota)'), naming the correct alternatives.

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

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

Annotations already declare readOnly/idempotent/openWorld=false, so safety is covered; the description goes further by disclosing cost and payment path ('Upstream quota, then $0.003 via x402'), the full return field set, and an alias name ('Also callable as get_model'). It stops short of describing error/rate-limit behavior or evidence freshness semantics in detail, so a 4 rather than 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?

Front-loads the core operation, then usage, then exclusions, then return values and cost. Every sentence adds distinct information with no filler; dense but not padded.

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 return fields (verdict, recommended_action enum values, replacement, shutdown_date, evidence, freshness) and the cost/quota path. Combined with the trigger conditions, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and the schema descriptions already say model is preferred and id is a legacy alias, so the description's 'Prefer model; id is only the legacy argument name' largely restates structured data. Baseline 3 applies since the schema carries the parameter burden.

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

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

States a specific verb (read/determine) and resource (one LLM model id's deprecation state) and enumerates the outputs: active/deprecated/retired, shutdown date, replacement. It explicitly differentiates itself from check_api_status and list_recent_api_changes, so an agent can disambiguate without opening schemas.

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

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

Gives concrete triggers ('before hard-coding a model id', 'when a call fails as model-not-found') and explicit exclusions with the correct sibling named for each ('Do not use it to see if the provider is down (check_api_status)', 'or to list many retirements (list_recent_api_changes)'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: it does not call the servers, does not consume a live-check credit, drops unsafe rows, and consumes the daily quota. It also discloses the return shape and an alias name, none of which appear in structured fields.

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

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

Purpose is front-loaded, followed by routing guidance, exclusions, behavioral costs, and return fields. Every sentence carries a distinct fact — usage, non-usage, side effects, output, quota, alias — with 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 enumerating the returned fields (summary, checked_at, alternatives[] with server, url, verdict, latency_ms, matching_tools). Combined with quota cost, alias, and sibling routing, an agent has everything needed to call and interpret 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%, so both parameters (query, limit) are already fully documented with type, range, default, examples, and the no-paging note. The description adds no further parameter syntax or format detail, 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 ('Search the Toolweather index for healthy MCP servers') plus the two distinct use cases (capability lookup vs. replacing a broken server). It explicitly distinguishes itself from check_mcp_server_health and watch_server by name, so an agent can route without opening schemas.

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

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

Gives explicit trigger conditions ('when check_mcp_server_health is unsafe or unknown, or when you lack a capability') and explicit non-use cases pointing to the correct siblings. Nothing about when to pick this tool over alternatives 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 already cover the non-read-only, non-idempotent profile, and the description adds substantial context beyond them: the 1,000 calls/day and 3-watch quotas, the one-time return of api_key that cannot be re-fetched, per-call secret uniqueness, the no-key fallback (50 calls/day), and the required X-API-Key header.

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?

Dense but front-loaded: the core action and its constraints come first, followed by return values and edge cases. Every sentence carries distinct operational information with 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 present, the description compensates fully by documenting the return payload (api_key, daily_limit, watches_limit) and the one-time-retrieval caveat. An agent has everything needed to call it correctly and only once.

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?

Zero parameters, so baseline is 4. The description reinforces this and adds meaning by noting 'Takes no arguments; the caller network is the limit,' explaining that per-network rate limiting substitutes for parameter-level control.

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 ('Mint one new Toolweather API key') with the exact format prefix (tw_…) and scope. It explicitly distinguishes itself from the sibling key tools spendgate_get_api_key and paycheck_get_api_key by naming their return prefixes.

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 when ('once per install', 'a few new keys per network per day, then reuse'), when-not ('do not call it every turn'), and alternatives ('do not use it when you need a SpendGate key … or a PayCheck key'). Nothing 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 already declare readOnly=true, idempotent=true, destructive=false, openWorld=false, so the safety profile is covered. The description adds genuinely useful non-structured context: it costs no Toolweather quota and no webhook, and it returns that issue's summary and items. It stops just short of noting freshness/update cadence beyond 'once a day'.

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 with zero filler; the purpose is front-loaded, then usage routing, then the cost/return note. Every sentence carries information an agent needs to select and call the tool.

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 read-only tool with one optional parameter and no output schema, the description covers what it returns, what it costs, and how to get the latest issue. Nothing material is missing for correct invocation.

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

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

Schema description coverage is 100% and already spells out the UTC YYYY-MM-DD format, the omit-for-latest default, and that it is not a timestamp or range. The description's 'Omit date for the latest issue' merely restates the schema, so it adds little beyond the 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 specific verb (Read) and resource (one daily digest) and enumerates its contents: incidents, model retirements, pricing-page edits, breaking MCP changes. It explicitly names the sibling it is not (list_recent_api_changes, check_api_status), so it is distinguishable 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 positive guidance ('Use once a day instead of polling list_recent_api_changes') and explicit exclusions with the correct alternatives for a live check and a filtered feed. Both when-to-use and when-not-to-use are covered, including the omit-date shortcut for the latest issue.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description goes further with billing behavior ('does not consume a score and is not billed'), session semantics ('anonymous cap...can reset on rotating egress'), and key-scoping rules ('a tw_ key does not select this cap'). This is meaningful context the annotations cannot express.

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

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

Front-loaded with the core purpose, then usage, then exclusions, then parameter nuance, then return scope. Dense but each sentence carries distinct information; only the api_key restatement is mildly redundant with the schema.

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

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

For a one-parameter read tool with no output schema, the description is complete: it names the return ('remaining SpendGate count only'), the billing and session caveats, and the routing to sibling quota tools. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, and the description adds genuine meaning: what kind of key api_key expects (sg_live_), what happens when omitted (anonymous IP/session cap), and its rotation caveat. It slightly restates the schema's own api_key description, which keeps it from 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 (read the remaining free SpendGate score count for this caller) and immediately distinguishes itself from the look-alike quotas in sibling tools (Toolweather health-check quota, paycheck_get_quota). An agent can identify the tool 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?

Explicit when-to-use ('before a run of score_spend calls') and explicit when-not-to-use, naming the three alternatives (Toolweather quota, paycheck_get_quota, key-minting tools). It even calls out which key type does not select this cap, leaving nothing 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 only cover the safety profile (readOnly, idempotent, non-destructive), and the description adds what they cannot: it takes no arguments, returns the catalog only, does not probe providers, does not consume the Toolweather check quota, and is free. Cost and side-effect disclosure of this kind is precisely the value structured annotations cannot carry.

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

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

Front-loaded with purpose, trigger, and scope before the caveats, so the critical information lands first. The four negative clauses ('Do not use it as...') are individually justified but make the middle of the description long and slightly list-like rather than flowing.

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 compensates by naming the returned fields (provider id, state, checked_at) and the possible state values. For a zero-parameter catalog tool with a fully covered safety annotation set, nothing an agent needs in order to call it correctly is missing.

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

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

There are zero parameters, so the rubric baseline is 4. The description confirms 'No arguments', which is consistent with the empty schema and removes any doubt an agent might have about passing filters.

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?

Starts with a specific verb+resource ('List the AI and developer API providers Upstream tracks') and immediately states the payload (state and checked_at), which is exactly what an agent needs to know before calling it. It also names the sibling it feeds into (check_api_status), so it is distinguishable from the other list/check tools 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 positive trigger ('Use to choose a provider id before check_api_status') and four explicit exclusions mapped to the correct alternatives (check_mcp_server_health, list_recent_api_changes, score_spend, check_merchant). The when/when-not/alternative triad is fully covered, leaving nothing 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 already declare readOnly/idempotent/non-destructive/closed-world, so safety needs no restating. The description adds genuinely non-obvious context: the return shape (summary plus items with timestamps and source links), the cost model (upstream quota then $0.01 via x402), and the get_changes alias. It does not mention pagination or rate-limit behavior, so it stops short of 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?

Four tight sentences, zero filler. Purpose comes first, then when-to-use, then anti-patterns with named alternatives, then return/pricing/alias — ordered by what an agent needs to decide and then call.

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 discharges that burden by stating the payload structure and item fields. Combined with full schema coverage and complete annotations, an agent has everything needed to invoke this 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 every parameter already carries a disambiguating description (e.g. 'Not a provider id', 'Not a page token'). The prose only hints at windowing via 'in a window', adding no syntax or format detail beyond the schema, 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?

Specific verb (List) plus the exact resource (recent outages, deprecation-page edits, model retirements, pricing-page edits across tracked AI/dev APIs). It explicitly names the two siblings it is not (check_api_status, get_digest), so the agent can discriminate 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 both a positive trigger (see what changed in a window, explain a sudden integration error) and explicit exclusions with the correct alternatives for each case. Nothing about tool selection 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 already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description goes well beyond that by disclosing that there is no quota charge, that the X-API-Key header is required and anonymous callers are rejected, and that it neither reveals webhook secrets nor probes servers.

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

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

Front-loaded with purpose, then usage and exclusions, then auth, then return shape — every sentence carries distinct, callable information despite the density. Nothing is redundant with the name or annotations.

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 contract itself, enumerating watches[] fields (id, server, webhook_url, active, disabled_reason, last_known, consecutive_failures, last_delivery) and free_tier. Combined with auth and scoping notes, an agent has everything needed to call it correctly.

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

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

Zero parameters, so the baseline is 4. The description confirms 'No arguments' and adds the quota-cost behavior, but there are no parameter semantics to enrich further.

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 ('List webhook subscriptions') plus the exact scope ('stored for the API key on this request'), including what the listing shows ('delivery health'). This clearly separates it from siblings like check_mcp_server_health and watch_server without needing to open 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 when-to-use ('to copy a watch id before unwatch_server, or to see failures') and explicit when-not ('Do not use it to learn if a server is up (check_mcp_server_health) or to create a subscription (watch_server)'), naming the correct alternative for each case.

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

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

Goes well beyond annotations: each call mints a distinct secret returned only once, it is not billed nor drawn from the Toolweather quota, and there is a 10-key per-IP-per-UTC-day rate limit. The non-idempotent, write-like nature is disclosed concretely rather than left to the hints.

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 what the key is and what it is for, then covers usage, exclusions, and limits. Every sentence carries distinct information (allowance lift, one-time return, billing, quota, rate cap) with 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 supplies the return semantics (a one-time secret to be passed as api_key), billing/quota behavior, and rate limits. Nothing an agent needs to call this correctly is missing.

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

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

Zero parameters, so the baseline is 4. The description confirms 'No arguments,' which is adequate given the empty schema; no further parameter meaning is needed.

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 (Mint) + resource (new PayCheck API key) and names the exact consumers (check_merchant, paycheck_get_quota). It also distinguishes its pc_live_ prefix from siblings' tw_ and sg_live_ keys, so an agent can tell it apart without opening schemas.

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

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

Explicit when-to-use (reach the 1,000/day merchant-check allowance), when-not (do not call every turn; not for Toolweather or SpendGate keys), and names the alternatives get_api_key and spendgate_get_api_key with their prefixes.

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

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

Goes well beyond the readOnly/idempotent annotations by disclosing that the call does not consume a check and is not billed, how key types (pc_live_, tw_, hex x-tw-bundle-client, anon:) select different caps, and the returned fields. This is richer behavioral context than structured fields 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?

Front-loads the purpose in one sentence, then layers usage, exclusions, and return values. Dense but each sentence carries information; the tier explanation is slightly sprawling but earns its place as non-obvious behavioral detail.

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

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

With no output schema, the description compensates by naming the return fields (subject_kind, limit, used, remaining, resets_at) and covering the zero-argument anonymous case. Nothing needed to call it correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real semantics: a pc_live_ key reads that key's own cap and a tw_ key does not select this cap. It reinforces rather than merely repeats the schema's exclusions.

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 ('Read how many free PayCheck merchant checks this caller has left today') with clear scope. It explicitly distinguishes itself from the similarly-named get_quota and the Toolweather quota, so an agent can route 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 explicit trigger conditions ('before a run of check_merchant calls, or after an HTTP 402') and explicit exclusions (not SpendGate's cap, not the health-check quota, not key minting). Alternatives are named with their exact sibling tool names.

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 readOnly/idempotent/non-destructive annotations, it discloses that the tool does not transfer funds, that scoring is deterministic (rewording won't change a v1 verdict), the exact return fields, and the quota/pricing model (100/day anonymous, 1,000/day with an sg_live_ key, then $0.001 via x402). That is rich behavioral context annotations cannot carry.

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?

Well front-loaded with the action and routing before less critical detail, and every sentence carries information. There is some overlap between description and per-parameter docs (the sg_live_ vs tw_ distinction appears twice), which costs a point on conciseness for a long definition.

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 scoring tool with no output schema, the description supplies the return values (score, verdict, reasons, recommended_action) and disambiguates key params and quota behavior. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: amount is USD not token units, api_key is an sg_live_ key not a tw_ key, and purpose is used as the category when category is omitted. These clarify cross-parameter relationships rather than restating 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 ('Score one planned payment') and the exact return contract (approve, ask_human, block) before any tool sends money. It explicitly distinguishes itself from siblings by naming what it is not (check_mcp_server_health, check_api_status, check_merchant, get_quota).

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 when-to-use ('Use before a crypto transfer, gift card, subscription, or paid API call') and when-not-to-use with the alternative for each case (uptime → health tools, trust → check_merchant, remaining quota → get_quota). No routing decision 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 declare non-read-only, non-idempotent, non-destructive, but the description adds behavior the annotations cannot: no required arguments, each call produces a different secret, the secret is returned only once, it is not billed, and it is not drawn from the Toolweather quota. That is exactly the extra context an agent needs before minting credentials.

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 most important facts (what it mints, which tools consume it, don't over-call it) are front-loaded, and each subsequent sentence carries non-redundant information such as quota/safety caveats. 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 zero-required-arg credential-minting tool with no output schema, the description covers invocation, return semantics ('Returns that secret once'), billing, quota, and the sibling alternative. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is already 100% and there is a single optional parameter, so the baseline is 3. The description usefully clarifies that label is a stored note rather than an auth secret, but it adds little beyond the schema text, which says virtually the same thing.

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 ('Mint one new SpendGate API key (sg_live_…)') and names the exact consumers (score_spend, get_quota). It also explicitly disambiguates from the sibling get_api_key by noting that one returns Toolweather tw_ keys, so an agent can route 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 explicit when-to-use, when-not-to-use, and the alternative: use once and pass the secret as api_key, do not call every turn, and do not use it when a Toolweather key is needed (get_api_key). No inference is required.

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 destructive=true, idempotent=true, openWorld=false, so the safety profile is covered; the description then adds context annotations cannot express — repeats are no-ops returning 'watch not found', get_api_key is a prerequisite, no contact with the MCP server, and no check quota is consumed. It is consistent with idempotentHint rather than contradicting 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?

Four compact sentences, each carrying distinct information (scope, when-to-use, when-not/alternatives, idempotency and preconditions). The core action is front-loaded and nothing is 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 one required string parameter, no output schema, and annotations carrying the mutation profile, the description closes the remaining gaps: the return shape {deleted: id}, the auth prerequisite, and the error behavior for unknown ids. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the parameter's own description already covers the 'w_… id from list_watches, not a server registry name' semantics. The description's 'Pass id from list_watches, not a server name' is a restatement rather than added 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 ('Delete one webhook subscription for this Toolweather API key') plus the side effect of dropping pending deliveries. An agent can distinguish it from watch_server (create), list_watches (read), and check_mcp_server_health without consulting 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 positive triggers ('stop alerts or free a watch slot') and explicit exclusions with alternative routes: use delete-then-watch_server to change a URL, and check_mcp_server_health to check health. The alternatives are named rather than implied.

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

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

Goes well beyond annotations: describes the dedup rule (same server+URL does not duplicate; different URL does), pricing (3 free, $0.05/30 days via x402), the returned one-time secret and signature header, downstream POST behavior, and that it does not consume the daily check quota. Annotations already give the safety profile, so this is substantial added context.

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

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

Front-loaded with the core action and dense with useful facts; every sentence contributes. Slight redundancy as the idempotency rule appears both in the body and in the webhook_url field, but overall well-structured.

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

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

Covers setup prerequisites, pricing/quota implications, dedup behavior, and return shape (id plus one-time secret) despite having no output schema. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter semantics by tying server and webhook_url together for idempotency ('The same server and webhook_url do not create a second watch; a different URL does'), which the individual schema fields don't express.

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 ('Create one HTTPS webhook subscription') and scopes exactly what it watches (verdict, auth requirement, breaking tool-list change). It explicitly distinguishes itself from check_mcp_server_health and list_watches, so an agent can route correctly without opening schemas.

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

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

Gives explicit when-to-use ('Use instead of polling check_mcp_server_health'), when-not ('Do not use it to read health now... or to list subscriptions'), and names the alternatives. Prerequisite (Toolweather key from get_api_key) is also stated.

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