AskYourStack

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds genuinely new behaviour: the Bing Webmaster Tools connection requirement, and a fallback where an empty list yields the site's total inbound links from crawl figures. That fallback is exactly the kind of non-obvious edge case an agent needs.

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 with no filler, front-loading the resource before the prerequisite and the fallback caveat. The second sentence packs prerequisite and edge case tidily, though the single long sentence is slightly heavy to parse.

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 read-only tool with no output schema, the description covers what comes back (top pages, per-page linking sources with anchor text), the auth prerequisite, and the empty-result behaviour. Nothing material 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 all three parameters are already documented, including the default/max for limit. The description only restates the page parameter's effect (who links to that page, with anchor text), adding little 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?

The description states a specific resource (inbound links Bing knows) and enumerates the two return modes: top-linked pages for a site, and linking outside pages with anchor text for one page. It identifies the Bing Webmaster Tools data source, which separates it from generic page_links or GSC siblings, but never names or contrasts with 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?

It gives one hard prerequisite ("Needs Bing Webmaster Tools connected") and the two modes are inferable from which parameter is supplied. However, there is no explicit when-to-use/when-not guidance and no pointer to an alternative tool for overlapping jobs like page_links or gsc_* backlink style 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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that, notably the retention window ('Bing keeps about 6 months') and the specific classes of data returned. It stops short of describing limits or pagination behavior for the 'limit' param.

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?

It is a single, front-loaded sentence that leads with the core behavior and packs in only substantive detail. It is somewhat run-on and could split the per-address and per-site clauses, 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?

With readOnly/idempotent annotations carrying safety and no output schema, the description does the needed work of enumerating return categories (index, errors, issues, find/last-crawl/response) and the 6-month retention. The main omission is clarifying the relationship between the url and site parameters and pagination of the limit-ed issue list.

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 url, site, and limit with defaults and bounds. The description only loosely gestures at the url parameter ('for one address') and adds no format or interaction detail beyond what the schema provides. Baseline 3 applies when the schema carries the load.

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

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

The description states a specific resource and specific data categories (daily crawled pages, index pages, crawl errors, per-address issues, plus find/last-crawl/response for one address). It is clearly a Bing crawl-data retrieval tool. It does not, however, name or distinguish itself from nearby siblings such as crawl_report, gsc_inspect_url, or page_audit, so an agent must infer the boundary 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?

Usage is only implied: the description hints at two modes ('crawl issues per address' vs 'for one address ... when Bing found and last crawled it'), which loosely maps to the site vs url parameters. There is no explicit when-to-use guidance, no statement of when to prefer this over gsc_inspect_url or crawl_report, and no note on whether url and site are mutually exclusive.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond that: the data is Bing's own (not a blended estimate), it is free via Bing Webmaster Tools, it returns week-by-week granularity, and it carries an interpretive caveat about not treating counts as total demand.

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

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

Two sentences, front-loaded with the purpose and data source before the caveat. Every clause carries information; the only mild redundancy is restating the Bing-ownership point. Appropriately sized for the tool's scope.

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 convey return values, and it does: search counts for the keyword, week-by-week breakdown, and related keywords with their counts. That covers what an agent needs to call and interpret the tool; only the exact date-range semantics and default handling are left entirely to the schema.

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

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

Schema coverage is 83%, so the schema documents most parameters (country, related, language, dates) already. The description hints at the date-period and related-keyword parameters ('in a period (week by week too)', 'related keywords') but adds no format or syntax 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?

States a specific resource ('keyword research') and verb-like action, and clarifies the data source as Bing's own counts with two concrete outputs (search volume over a period, week-by-week breakdown, and related keywords with counts). It clearly distinguishes itself from Google-based tools by emphasizing Bing data, but it never names the close siblings (keyword_volume, keyword_ideas, domain_keywords), so the agent must infer the distinction.

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

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

The description gives an interpretation caveat ('use them to compare keywords against each other and to see trends, not as a keyword's total search demand'), which is useful guidance on how to use the output. However, it gives no when-to-use-vs-alternatives guidance, e.g., when to pick this over keyword_volume or keyword_ideas, leaving tool selection 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 readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds a genuinely useful behavioral fact not in the structured data: Bing retains roughly six months of history, and the comparison window is fixed at 28 days vs the preceding 28. It does not discuss rate limits or result truncation beyond the schema's limit.

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 what is returned, then the parameter-routing guidance, then the sibling pointer — a sensible order with no filler. The first sentence is long and packs several distinct report sections, which slightly hurts scannability, but nothing is wasted.

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

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

With no output schema, the description does the job of describing returns (daily metrics, 28-day comparison, top queries/pages with impressions, clicks, average position) and adds a retention caveat. Combined with the 75%-covered schema for site/limit/page, an agent has enough to call it correctly; only permission/precondition details are absent.

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

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

Schema coverage is 75% and the `query` parameter has no schema description at all, so the description carries real weight here by explaining that `query` pivots to landing pages and `page` pivots to queries. That is meaning beyond the schema. It does not clarify the site-matching or limit interaction further, but the key ambiguity is resolved.

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 ('Bing search performance of a site') and enumerates exactly what is returned: daily impressions and clicks, 28-day vs prior-28-day comparison, top queries and top pages with impressions, clicks and average position. It explicitly positions itself against the sibling gsc_performance_overview, so an agent can distinguish the two 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 concrete routing rules for two parameters: 'Pass query to see the pages one query lands on, or page to see the queries one page gets', and points to gsc_performance_overview for Google data. This is clear usage context, but it never states when not to use the tool or what preconditions (e.g. a connected Bing site) are 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 cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true), and the description adds useful output context: status, last-read date, and address count. It does not cover auth requirements or rate limits, but for a read-only listing tool it adds meaningful behavioral detail 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?

Two sentences, zero waste. The core purpose and returned fields are front-loaded, and the alternative is relegated to the second sentence.

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

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

For a simple read-only Bing sitemap listing tool with rich annotations, 100% schema coverage, and no output schema, the description is complete enough. It says what is returned and routes the agent to the correct tool for submission.

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 single optional site parameter is fully documented in the schema. The description adds no parameter syntax or format detail beyond what the schema already provides, which matches the baseline 3 for high schema coverage.

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

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

The description states a specific resource and scope: 'The sitemaps Bing knows for a site, with status, when Bing last read them, and how many addresses they hold.' It distinguishes from the sibling bing_submit by naming it as the submission alternative, so an agent can tell what this tool does 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 gives an explicit alternative for submission: 'To submit one, use bing_submit with sitemap.' That is a clear when-not/alternative cue, though it does not explicitly compare against other retrieval siblings like gsc_sitemaps or sitemap_check.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context beyond the annotations: the return includes per-site AI read permissions (a non-obvious access-control field) and it enumerates the scope of the underlying Bing Webmaster Tools data (queries, pages, crawl errors, links, URL submission, sitemaps).

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

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

Two sentences, front-loaded with the actual resource and its permission aspect. The second sentence is background on what Bing Webmaster Tools is; it earns partial credit by disambiguating Bing from the many Google Search Console siblings, but it is closer to contextual padding than operative instruction.

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

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

For a parameterless, read-only listing tool with no output schema, the description tells the agent what it gets back (sites plus read permissions) and where that permission is configured (the SEO page). Nothing essential to calling it correctly is missing, though it stops short of saying how to proceed once the site list is obtained.

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 carries no semantics to supplement; baseline for a no-param tool is 4. The description correctly implies the tool is account-scoped with no filtering inputs.

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

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

The description names the resource precisely (sites in the user's Bing Webmaster Tools account) and adds a distinct output dimension: which sites the AI is permitted to read. It is a noun phrase rather than a verb-led statement, and it does not explicitly distinguish itself from sibling listers such as list_sites or connected_sites, but the 'Bing Webmaster Tools' scoping makes the intent unambiguous within the bing_* family.

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 only implied: the mention of read permissions and the explanation of what Bing Webmaster Tools covers hints that this is the discovery entry point before calling bing_performance, bing_backlinks, etc. There is no explicit 'use this when' statement and no exclusion of alternatives, so an agent must infer the routing.

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, open-world write, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: the 500-address cap, the ~10,000/day per-site quota and that remaining quota is surfaced, and the account prerequisite. It does not say how partial failures or rejected URLs are reported.

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 front-loaded sentences, with the action and its limits stated before the alternative-tool routing. The first sentence is dense with nested parentheticals, which slightly taxes readability, but no sentence 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?

No output schema exists, but the description covers the mutation's constraints, quota behavior and the alternative route, and annotations carry the safety hints. It stops short of explaining what a submission result or a failure looks like, which is the main remaining gap for a write 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 description coverage is 100%, so the schema already documents site, urls and sitemap. The description adds only the volume ceiling on urls, not format or validation semantics. Baseline 3 is correct when the schema does the heavy lifting.

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 and resource ('Ask Bing to crawl pages now', submit addresses or a sitemap) with concrete scope limits (up to 500 addresses, ~10,000/day per site). It also names the sibling it overlaps with (indexnow_submit), so an agent can distinguish it 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?

Explicit trigger ('Use after publishing or changing pages') plus an explicit alternative and the condition that selects it: prefer indexnow_submit when no account exists, prefer this when Bing is connected and the user wants Bing's own confirmation and quota.

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, open-world), so the description's added value is data-boundary disclosure: proxied traffic only, a 30-day ceiling, fixed 24-hour windows for hourly/top-country/firewall data, and that firewall events are only a 'sample'. It does not mention auth/token requirements or whether any fields can be empty.

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 resource, zone scope and the 'proxied traffic only' constraint, then the output inventory, then a short usage cue. The long enumerated list is information-dense rather than padded, and with no output schema that detail earns its place, though the single run-on sentence is heavier than necessary.

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 comprehensively (metrics, time windows, top countries, hourly, firewall-event sample). Combined with annotations and full schema coverage, the only real gap is operational context such as permissions and whether the firewall sample is truncated.

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 both parameters (days 1-30 default 7, zone optional for single-zone users) are fully documented in the schema. The description's 'per day for up to 30 days' and 'last 24 hours' windows loosely mirror the days parameter but add no syntax or format detail beyond it, 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?

The description states a specific resource and scope: 'Traffic through Cloudflare for a zone (proxied traffic only)', followed by an explicit inventory of the metrics returned. That scope cleanly separates it from the other cf_* siblings (DNS, firewall rules, cache, settings, zones), which are configuration tools rather than read-only analytics.

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 place to look during a bot attack or a traffic alert' gives a concrete triggering context, and 'proxied traffic only' implicitly scopes out non-proxied/GA-sourced data. It stops short of naming an alternative (e.g. ga4_* or cf_firewall_list for rule configuration), so no explicit when-not-to-use guidance.

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

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

Annotations already disclose the write profile (readOnly=false, idempotent=false, destructive=false, openWorld=true), lowering the bar. The description adds two useful facts beyond them: proxied defaults to false, and the record can be reversed via cf_undo. It still omits auth/permission needs and any rate-limit context, so it is solid but not rich.

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

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

Two tight sentences, front-loaded with the core action and examples, with no filler. Slightly under-elaborated on routing but nothing wasted.

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

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

With no output schema required and annotations carrying the safety profile, the description covers purpose, examples, the proxied default, and the reversal path. The only gap is the lack of differentiation from cf_dns_change, which keeps it from a 5.

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

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

Schema description coverage is 89%, so the schema already documents all 9 parameters well, including the proxied default. The description only repeats the proxied default and adds no new meaning for type/name/content/data, 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 (Add) and resource (DNS record to a Cloudflare zone) and gives concrete examples of what can be added (subdomain, mail record, verification text). It does not differentiate itself from the sibling cf_dns_change, which an agent might confuse with it, so it falls short of a 5.

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

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

Usage is implied by the 'Add' framing, and it usefully points to cf_undo for removal, but it never states when to prefer this over cf_dns_change or what prerequisites (e.g. an existing zone) are needed. This is the minimum viable routing guidance.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, so the safety profile is known. The description adds genuinely new context: the pre-existing-record restriction requiring elevated mode, and that cf_undo restores prior values — real behavioral detail beyond annotations. It stops short of clarifying partial-update semantics for a tool whose 11 params are all optional.

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 the core action, followed by record targeting, the prerequisite, and the reversal path. No filler or repetition of the 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?

For an 11-parameter destructive mutation with no output schema, the description covers record identification, a non-obvious prerequisite, and rollback. The only notable gap is whether unspecified fields are left untouched or cleared, which an agent would want before mutating.

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 91%, so the schema already carries nearly all parameter meaning. The description adds only light framing (which fields can be changed, how record_id resolves), so the baseline 3 is appropriate rather than a higher mark.

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 (change one DNS record of a Cloudflare zone) and enumerates exactly which fields are mutable (content, TTL, proxy, priority, name). This clearly separates it from cf_dns_add, cf_dns_list, and cf_dns_remove 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?

Explains how to target the record (record_id from cf_dns_list, or name plus type when they match exactly one record) and states a real prerequisite: records predating AskYourStack require the connection's "change anything" mode. It also points to cf_undo for reversal, though it never explicitly says when to prefer cf_dns_add over this tool.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description's 'Changes nothing' reinforces the read-only nature but adds no new behavioral context such as rate limits, auth requirements, or pagination.

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 zero waste, front-loading the core action and filtering options before the no-side-effect assurance. Every part 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 simple list tool with full schema descriptions and rich annotations, the description is nearly complete. It does not mention pagination or default behavior when no filters are applied, but with no output schema that 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 100%, so the schema already fully documents all four parameters. The description mentions filtering by type, name, or search but adds no syntax or format details beyond what the schema provides.

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 the specific verb 'List' and resource 'DNS records of a Cloudflare zone', and clarifies filtering options. It distinguishes itself from mutation siblings implicitly via 'Changes nothing', but does not explicitly name alternatives like cf_dns_add.

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?

Provides no explicit when-to-use or when-not-to-use guidance. There is no mention of alternatives or conditions for choosing this tool over cf_dns_add, cf_dns_change, or cf_firewall_list.

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 destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered structurally. The description goes beyond that by naming the permission mode needed for pre-existing records and pointing at cf_undo as the reversal path — real behavioral value. It stops short of describing what happens when name+type match zero or multiple records.

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, no filler: target and identification method first, then the permission caveat, then the undo remedy. Everything is front-loaded and each sentence carries unique 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?

With no output schema, the description still covers identification, permission prerequisite and reversibility — enough for an agent to invoke it correctly. Minor gaps remain around ambiguous-match behavior and whether confirmation is expected before a destructive call.

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

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

All four parameters have full schema descriptions (100% coverage), including the same name-plus-type fallback and id-source notes the description repeats. The description adds only a slight emphasis on preferring record_id from cf_dns_list, so the schema is doing the heavy lifting.

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 (Remove) and resource (one DNS record of a Cloudflare zone) with an exact scoping mechanism (record_id from cf_dns_list, or name plus type). This cleanly separates it from cf_dns_add and cf_dns_change without the agent needing to open 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 a concrete prerequisite (records pre-dating AskYourStack require the connection's "change anything" mode) and a recovery route (cf_undo recreates it). It does not explicitly say when to prefer cf_dns_change over this tool, but the destructive verb makes the split clear enough.

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 destructiveHint=true and openWorldHint=true, but the description adds genuinely new context: that the rule 'can block real visitors' and the exact reversal path via cf_undo/cf_firewall_remove. This is meaningful beyond the safety flags, though it omits permission requirements and success 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?

Three dense but front-loaded sentences: the action leads, the matching model follows, and the safety/reversal note closes. Every sentence earns its place, though the middle sentence is long and packs many fields together.

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 destructive, open-world write tool with no output schema and partial param coverage, the description supplies the matching model and the critical reversal path. It is largely complete, missing only success/permission details that the annotations partly cover.

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?

With 17 params at 35% schema coverage, the description carries real weight by explaining how matching fields combine ('combined with and') and field semantics like path (starts with) and user_agent (contains), plus the raw-expression alternative. It leaves parameters like enabled and description unexplained, so not fully compensating.

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 ('Add one firewall rule or rate limit to a Cloudflare zone'), distinguishing it cleanly from cf_firewall_list and cf_firewall_remove. An agent can identify exactly what this tool does 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?

Explicitly routes the agent to cf_undo and cf_firewall_remove for reversal and explains the match-combination model, giving clear operational context. It stops short of naming when NOT to add a rule (e.g., preferring cf_firewall_list to inspect existing rules first), so it lacks full exclusions.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so 'Changes nothing' largely restates them. However, the description adds genuine value by disclosing the shape of the response (id, action, expression) in the absence of an output schema, which the annotations do not cover.

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 zero filler; every clause (scope, returned fields, no side effects) 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 simple read-only list tool with full annotation coverage and a fully documented parameter, the description is largely sufficient, covering scope and return fields. It could note pagination or result ordering, but nothing critical is missing.

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

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

Only one parameter exists and its schema description coverage is 100%, so the schema fully explains the 'zone' argument. The description adds no extra meaning about the parameter, making the baseline 3 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 ('List') and resource ('custom firewall rules and rate limits of a Cloudflare zone'), and even names the returned fields (id, action, expression). This cleanly separates it from the sibling mutation tools cf_firewall_add and cf_firewall_remove.

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 'Changes nothing' implies a safe read operation, and the name distinguishes it from the add/remove siblings, but there is no explicit when-to-use or when-not-to-use guidance and no named alternatives. Usage is only implied.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the danger profile is covered. The description adds genuinely useful context beyond them: the removal is reversible via cf_undo, which is not derivable from 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?

Two short sentences with zero padding; the destructive action and its identifier source are front-loaded, and the recovery hint is a compact second sentence.

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

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

For a destructive, output-schema-less tool whose annotations carry the safety profile, the description supplies the essentials: target, id source, and reversal path. It is slightly thin on the optional zone parameter, but the schema covers that.

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 50% — zone is documented in the schema, rule_id is not. The description compensates for rule_id by specifying its origin (cf_firewall_list), but adds nothing about the zone parameter, so it lands at the baseline for partial coverage.

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

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

States a specific verb (Remove) plus the resource (custom firewall rule or rate limit) and its scope (Cloudflare zone), and the mechanism (by rule_id). This cleanly separates it from siblings cf_firewall_add and cf_firewall_list.

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

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

It tells the agent where rule_id comes from (cf_firewall_list) and names the recovery alternative (cf_undo), which is clear routing guidance. It stops short of explicit when-not-to-use conditions, but the context 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 destructiveHint=true and idempotentHint=false, so the safety baseline is set. The description adds genuinely new behavior: the purge is irreversible but self-healing ('the cache fills again from the origin') and the per-request URL limit of 30. It stops short of noting the origin-load consequence of a full-zone purge or any auth/permission requirement.

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: scope first, then the usage trigger and reversibility note. No filler, no restatement of the title, everything front-loaded.

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

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

For a 3-parameter mutation tool with no output schema, the description covers what is cleared, when to use it, the extent limit, and the post-purge behavior. Only minor gaps remain (whether confirmation/return output exists, any zone-permission caveat), which are not critical to invoking 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% — urls and zone are documented, the boolean 'everything' is not. The description compensates by explaining the everything-vs-addresses dichotomy and surfacing the 30-URL cap, which appears nowhere in the schema. That is real added value above 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 and resource — clear Cloudflare's cache of a zone — and immediately enumerates the two scopes (everything, or given addresses up to 30). It is unmistakably distinct from sibling cf_* tools like cf_dns_* or cf_settings 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?

Explicitly gives the triggering situation: after deploying changes when a visitor still sees the old page or a wrong page is cached. It does not name a sibling alternative, but the line 'Nothing to undo' implicitly rules out reaching for cf_undo/rollback.

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 flag this as non-read-only, destructive, and non-idempotent, so the bar is lower. The description still adds real value beyond them: it discloses that changes are reversible via cf_undo, that under_attack false restores the prior level, and that development_mode is a temporary 3-hour cache bypass.

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

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

Purpose and mode behavior are front-loaded, and most clauses earn their place by naming values or clarifying shortcuts. The middle sentence is dense and slightly run-on, but there is no padding or redundancy.

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

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

For a 9-param mutation tool with no output schema, the description covers modes, reversible undo, and the key settings. The main gap is that some parameters (min_tls_version, browser_check, automatic_https_rewrites) are listed without any value or effect explanation, and the read-mode return shape 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 coverage is only 11% (just the zone param), so the description must compensate. It does supply enum values for security_level and ssl that the schema lacks, and groups settings by mode, but leaves min_tls_version values and the semantics of browser_check/automatic_https_rewrites unexplained, so compensation is partial.

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 pair (read or change) and resource (Cloudflare zone settings), then enumerates the exact settings involved. It is clearly distinguishable from siblings like cf_dns_add, cf_firewall_add, and cf_purge_cache, which target different Cloudflare resources.

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 the two modes (no args = read all; passing args = change) and routes undo to cf_undo, which is helpful. However, it never explicitly states when to use this tool versus other settings-adjacent siblings, nor any when-not-to-use conditions.

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

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

Goes well beyond the annotations by spelling out the exact reversal semantics per operation type: an added record/rule is removed, a changed one is restored to old values, a removed one is recreated. This is materially useful given destructiveHint=true and idempotentHint=false, and it also discloses the default listing window of 90 days.

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, no filler. The core undo behavior is front-loaded and the no-argument fallback is placed second, which is the right priority order for an agent deciding how to call it.

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, no-output-schema tool with annotations already declaring the destructive profile, the description covers purpose, reversal semantics, and default behavior. It does not address permissions/auth needed to undo or whether the undo itself is reversible, which would be nice for a destructiveHint=true 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 0% and the single attribute has no description, but the prose fully compensates by explaining the effect of supplying change_id versus omitting it (falling back to a 90-day listing). It stops short of saying where to obtain a change_id, though the listing behavior implies it.

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

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

States a specific verb (undo) plus the resource (a Cloudflare change) and narrows the scope to changes made by the cf_dns_, cf_firewall_ and cf_settings tools. An agent can distinguish this from sibling undo tools like redirects_undo or content_undo by the Cloudflare scope alone.

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 context for both invocation modes: with change_id it undoes that change, without it lists changes from the last 90 days. It does not explicitly name non-Cloudflare alternatives (rollback, redirects_undo) or state exclusions, so it falls just short of the 5 bar.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new context beyond that: the returned fields, the notion of per-zone AI permissions ('what the AI may do there'), and the auth/setup requirement (API token via the Sites & Apps page, no server needed).

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 the resource and the 'start here' directive front-loaded. No filler, and the setup/auth note is compressed into one 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?

With no output schema and no parameters, the description carries the burden of telling the agent what comes back, and it does so by listing status, plan, name servers and permissions. Combined with the entry-point guidance and auth context, 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?

This tool takes zero parameters, so the absence of parameter discussion is expected and the baseline of 4 applies. Nothing in the description misrepresents the no-argument nature of the call.

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 names the specific resource (Cloudflare zones/domains the user connected) and enumerates what each entry carries (status, plan, name servers, permissions). The line 'Start here before any other cf_ tool' distinguishes it from the many cf_dns_*, cf_firewall_* and cf_analytics siblings.

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 an explicit sequencing rule ('Start here before any other cf_ tool'), which is exactly the routing guidance an agent needs when facing dozens of cf_ tools. It stops short of naming when *not* to use it or which specific sibling to follow with, so it is clear context rather than full when/when-not coverage.

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, openWorld, so the safety profile is covered. The description adds genuinely new context: what each entry contains (name, address, kind, mode, content kinds, content_save fields) and the cross-tool routing. It stops short of noting pagination or auth prereqs, which is a minor gap given annotations carry the rest.

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

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

Three tight sentences, front-loaded with the defining scope before the routing and exclusion details. The middle sentence listing returned fields is dense but earns its place since no output schema exists.

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 describe the return shape, and it does (name, address, kind, mode, WordPress content kinds and content_save fields). Combined with the explicit sibling routing, 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 there is nothing for the description to disambiguate; baseline is 4. It usefully describes the shape of each returned record even though that goes beyond strict parameter semantics.

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 resource and scope: sites the user connected without a server, split into WordPress-via-REST and WhizzyCommerce-via-connector. It explicitly excludes server-hosted sites and names the sibling that covers them, so an agent can distinguish it from list_sites without opening anything.

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 routing in both directions: use content_ tools on a WordPress site, whizzy_tools and whizzy_call on a WhizzyCommerce shop, and use list_sites/wp/db_query for server-hosted sites. The when-not condition is stated, not inferred.

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, and non-destructive, so the safety profile is covered. The description adds real value by clarifying that content is 'the stored source' (raw, editor-view) and listing platform-specific return fields, which goes beyond what the annotations 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?

Core purpose is front-loaded in the first clause, and the following platform detail is informative rather than filler. The WordPress/Shopify field enumeration is somewhat long but earns its place by telling the agent what to expect.

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, listing the fields per platform and clarifying the raw-source nature of content. Minor gaps remain: what 'id' refers to and how ids are obtained, but the tool is otherwise complete.

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

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

Schema coverage is 67%; the site parameter is well documented and references connected_sites, but the required 'id' has no description and 'type' is only 'Default post.' The description provides no parameter-level guidance to compensate, so 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 item of a connected site'), and immediately scopes it against the sibling list-style tool by emphasizing a single item read 'in full'. It enumerates the returned fields per platform, so an agent knows exactly what this retrieves versus content_list.

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

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

The single-item framing implies usage versus content_list, but there is no explicit when-to-use/when-not statement or named alternative. The agent must infer the routing from the resource scope rather than being told.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-structured behavior: ordering ('newest change first') and pagination limits ('20 a page, up to 100'), which the annotations do not convey. Returned fields are also enumerated, though pagination cursor mechanics less so.

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, then platform coverage, returned fields, filters and pagination in a tight sequence. It is dense with almost no filler, though the WordPress/Shopify type enumeration is somewhat list-heavy and could be compressed.

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

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

With no output schema, the description usefully enumerates the returned fields (id, title, status, address, change time, alt text) and covers filters and paging, which is most of what an agent needs. The gap is that media_type's role and the meaning of the page cursor are left to the schema.

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

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

Schema description coverage is 57%, so baseline is 3. The description compensates somewhat by defining search as words, listing status values, and giving the per_page default/max ('20 a page, up to 100'), but it partially duplicates the schema's type and status text and never explains media_type (image/video/audio/application), leaving one enum-gated parameter undocumented in both places.

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 ('List') and resource ('content of a connected site') and immediately scopes it by platform (WordPress vs Shopify content types), which cleanly separates it from siblings like content_get, content_save, content_upload and content_trash. An agent can identify this as the enumeration 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?

It gives implied usage through filters ('Filter with search (words) and status') and default types per platform, but never names an alternative or states when not to use this tool (e.g., versus content_get for a single item). The agent must infer the listing-vs-fetch boundary from sibling names alone.

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 destructive/not-idempotent/openWorld, but the description adds material context they don't carry: draft-by-default behavior, the site-mode gating rules, that prices/stock/variants are never touched, 90-day change retention, the content_undo recovery path, and where the preview link appears. This is well beyond the annotation surface.

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 and the create/update switch, and every subsequent sentence carries actionable content (modes, field sources, undo, warning). It is dense and long, but not padded – a slightly tighter grouping of the field-variation detail would read better.

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

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

Given a 4-param tool with a nested `fields` object, destructive semantics, and no output schema, the description covers everything an agent needs: how to create vs update, which fields are legal, mode gating, recovery, and that a preview link is returned. 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 coverage is 75%, and the description meaningfully enriches it: id absence means create, fields vary by site/item kind, and it names the concrete fields (title, content, slug, status; Shopify extras). It does not discuss the `type` parameter (schema only says 'Default post'), leaving one facet thinner than 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?

States a specific verb pair (create/change) and resource (content on a connected site), and immediately disambiguates the two modes: 'Without id it creates... with id it changes only the fields you pass.' An agent can tell this apart from content_get, content_list, content_trash, and content_undo without opening their 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 branching (id present vs absent), points to connected_sites for the field list and to content_undo for reverting, and states a clear when-not: 'Never publish or change live content unless the user asked for exactly that.' The mode constraint ('drafts only... publish too') tells the agent what the environment permits.

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 flag destructiveHint=true and non-idempotency, but the description adds behavior they cannot express: the 30-day retention window, the recovery path via content_undo, the drafts-only-mode restriction, and the scope boundary ('Nothing else is deleted through a connection'). That is meaningful consequence disclosure for an irreversible-feeling action.

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 dense sentences, front-loaded with the primary WordPress action before the Shopify variant, and no filler. It is on the long side for a single paragraph but essentially every clause carries operational 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?

With no output schema, the description still conveys what happens after the call (recoverable via content_undo for 30 days) and where the tool does not apply. The only real gap is the required id parameter's semantics, which is left entirely to the caller to infer.

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% and already documents site (name or address) and type (default post). The description adds context about which item classes are valid (post, page, URL redirect) but never explains the required id parameter — its format, whether it is a numeric ID or a URL for redirects. Baseline 3 is appropriate since the schema does 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 ('Move a post, page or other item ... to its trash') and extends it precisely to a second case ('remove a URL redirect of a Shopify store'). It distinguishes itself from content_undo by naming the inverse relationship, so an agent can pick between the two 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 mode conditions ('In drafts-only mode this works for drafts; removing something live needs the publish-too mode') and an explicit when-not ('Shopify has no trash, so take a product or page off the store by setting its status to draft or archived'). Alternatives and exclusions are both 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 (destructiveHint=true, readOnlyHint=false, idempotentHint=false). The description adds real behavioral detail beyond that: the per-case semantics of what undo actually does, plus the 90-day window and the list-instead-of-revert fallback when change_id is absent. It omits auth/permission requirements, keeping it at a 4.

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

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

Two sentences, front-loaded with the undo action and its case-by-case effects, followed by the no-argument fallback. No redundant restatement of the title 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?

For a 2-param mutation tool with no output schema and annotations already carrying the safety flags, the description covers the key unknowns: what gets changed in each scenario and the listing fallback. Lacking output/permission detail, but nothing critical 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 50% (site documented, change_id bare). The description compensates for the undocumented change_id by explaining that omitting it triggers a listing mode and that ids come from that listing, which the schema does not convey. It does not specify the id's origin format beyond 'ids', so it is 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 (undo) and the exact resource scope by naming the sibling operations it reverts (content_save, content_upload, content_trash). It then enumerates the three concrete outcomes (edit reverts, create trashes, trash restores), so an agent immediately knows what this does and how it differs from generic undo siblings.

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?

Explains the primary condition (undo a prior content_* operation) and a second mode: omitting change_id lists changes from the last 90 days with their ids. This effectively documents a discovery workflow. It stops short of explicitly routing the agent away from other undo tools (cf_undo, redirects_undo, seo_fields_undo), but the operation-scoped wording does most of that work.

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 non-read-only, open-world, non-idempotent, non-destructive) the description adds hard limits — accepted formats jpeg/png/gif/webp/avif, 15 MB each, up to 10 per call — the WordPress return shape (media ids for featured_media or inline content), and the drafts-only caveat that an unused image is invisible. It does not cover permission/auth requirements or failure behavior, so it is strong but not exhaustive.

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 purpose and the input-mode choice are front-loaded in the first clause, and every later clause carries operational information (formats, limits, platform-specific follow-up, drafts mode). It is dense — semicolon-chained — and could be broken into a short bullet list for scanability, but 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?

For an 8-parameter mutation tool with no output schema, it supplies the missing pieces: accepted formats and size/count limits, which parameter feeds which kind of image, what the response yields on WordPress, and how the result is consumed downstream. Only failure modes and duplicate handling are 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 coverage is already 88%, so the baseline is 3; the description nonetheless clarifies intent the schema leaves open — that `images` and `url` are mutually exclusive in spirit (one image via url), and that `data_base64` is a constrained fallback for one small image. It also implies alt_text/alt_texts/title are applied at upload time, matching the schema's per-call alt-text rule.

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 gives a specific verb (add/upload) and resource (images to a site's media library / files) and names the two platforms (WordPress, Shopify) whose behavior differs. It is clearly distinguishable from siblings like content_save (which attaches media) or convert_images (which transforms it).

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 explicitly routes between the three input modes (conversation `images`, public `url`, `data_base64` as a fallback for clients that cannot pass files) and states what to do next on each platform (content_save add_image / image_url). It also notes drafts-only mode is permitted. It stops short of naming when NOT to use it (e.g. format conversion via convert_images).

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 give the broad profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true); the description adds the details that matter: runs as the site's owner in the background, originals are never changed, non-smaller copies are removed, already-converted files are skipped, and the job summary's contents. It also discloses environment dependence (encoder availability, 'or says what to install').

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 action, but the remainder is a single dense block with heavy parenthetical nesting that is hard to scan. The serving-configuration paragraph (nginx map, Apache RewriteCond, platform settings) is legitimately useful guidance but would read far better as separated clauses or bullets.

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, and the description compensates fully by telling the agent how to retrieve results (follow with job_output) and what the final line contains (converted, already had a copy, no gain, MB before/after). Background execution, idempotent re-runs and the serving caveat are all covered.

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 high (86%) and already documents site, format, folders, quality and max_files, so the baseline is 3. The description adds real semantics on top: 'dry_run true only counts' (a mode the schema never explains) and the WebP-vs-AVIF tradeoff reasoning, plus the default folder set in prose.

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 and resource ('Make WebP (or AVIF) copies of the JPEG and PNG images in a site's upload folders'), names the output artifact convention (<file>.webp) and the encoders used. It is unmistakable against siblings like job_output, which it positions itself as a precursor to.

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-run ('Tell the user that before converting ... and run it again later for new uploads (existing copies are skipped)'), when-to-use-adjacent alternatives (nginx map/try_files, Apache RewriteCond, WordPress/Magento image settings for serving), and the dry_run preview mode. Nothing about invocation timing 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 establish read-only, idempotent, non-destructive, open-world behavior, so the bar is lower; the description goes well beyond by disclosing the no-data limitation for low-traffic pages, the origin fallback, the ~30 s latency of the lab test, and the ~6-month span of the history trend. These are exactly the operational traits an agent needs to set expectations and avoid misinterpreting empty 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?

Content is front-loaded with what the tool returns, and most clauses earn their place (data source, metrics, split thresholds, fallback). It is a dense pair of run-on sentences, so it is slightly heavier than ideal, but very little is wasted.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does: metrics, percentile, good/needs-improvement/poor buckets, LCP breakdown components, and the empty-result case. Combined with the annotation-covered safety profile and 80% schema coverage, an agent has everything needed to call and interpret 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?

With 80% schema coverage the baseline is 3, but the description adds meaning the schema lacks—notably that history=true yields a weekly trend over ~6 months (the schema gives no description for history at all) and how url vs origin select page vs site scope. It reinforces rather than merely repeats the lab and form_factor semantics.

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

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

The description names the specific data source (Chrome UX Report / CrUX field data), the resource (a page via url or a site via origin), and the exact metrics returned (LCP, INP, CLS with 75th percentile and good/needs-improvement/poor splits, plus FCP, TTFB, and LCP sub-parts). An agent can distinguish this from every sibling (page_audit, ga4_*, gsc_*) 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?

It clearly explains the two addressing modes (url for one page, origin for a whole site), what history=true and lab=true add, and the fallback rule when a page has too little Chrome traffic (origin is tried). It stops short of naming alternatives among siblings or stating when-not-to-use it, so 4 rather than 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description goes further by disclosing the analyzable window (default 24h, up to 168), that it reads access logs, and that Googlebot/Bingbot are verified via reverse DNS including identification of spoofed addresses. It does not discuss rate limits or auth, but adds substantial context beyond annotations.

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

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

The core purpose is front-loaded, and every clause is informative, but it is delivered as one long run-on sentence with an embedded colon-list that is hard to parse. Appropriately sized for the tool's richness but poorly structured for a scanning agent.

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 hits, status codes, page categories, query-string URLs, top/404/5xx paths, per-hour Googlebot/Bingbot hits, and spoofing detection. Combined with the three documented parameters and safety annotations, an agent has enough to invoke 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%, so each parameter is already documented in the input schema, and the description largely restates those values (24/168 hours, combined-format log). It adds only a mild clarification of the log/server relationship when multiple servers exist, so the baseline 3 is appropriate.

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

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

States a specific verb+resource: reporting what search/AI/SEO crawlers fetched from the web server's access logs, with an explicit enumeration of what is measured. It distinguishes itself from the many gsc_* and bing_* siblings by framing itself as a log-side technical SEO tool used 'next to Search Console data'.

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

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

Gives a clear use context ('technical SEO (crawl budget, errors served to Google)') and a routing instruction for the multi-server case ('Pass log for one site's access log when the server has several'). It implies complementarity with Search Console tools but does not name a specific alternative or an explicit when-not-to-use, so it stops short of a 5.

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

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

Adds real context beyond the annotations: async execution, the job_id + file path return, the fixed output directory /var/lib/askyourstack/dumps, credential handling ('they never reach the chat'), and a transfer hint. It is consistent with the declared non-destructive, non-idempotent, open-world profile, but does not say what happens on a repeat run (the non-idempotent case) or how failures surface.

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 action and result, and every sentence carries information (return values, storage path, follow-up tool). It is slightly run-on with several clauses chained by semicolons, but nothing is wasted.

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

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

With no output schema, the description carries the return-shape burden and does so (job_id and file path). It covers destination and transfer, but leaves failure modes and retrieval of the finished file unaddressed for an async mutation tool.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema, including their optionality and format examples. The description's only marginal addition is implying the site argument ties back to list_sites; 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 (dump) and resource (a site's database), plus the output artifact (.sql.gz file on its server), which distinguishes it cleanly from siblings like db_query, db_restore, and list_dumps. The parenthetical '(any kind list_sites shows)' further scopes what databases are eligible.

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 operational context: it runs in the background and the agent should 'follow it with job_output', which is actionable workflow guidance. It does not explicitly contrast with db_query/db_restore or state when not to use it, so it stops short of full when/when-not routing.

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 give coarse hints (destructiveHint=true, readOnlyHint=false, openWorldHint=true); the description usefully refines this by splitting read-only statements from mutating ones, disclosing that the site's own credentials are used with no password needed, and describing the approval flow. It stops short of mentioning row-limit or result-format 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?

Three tight sentences with the core action front-loaded, followed by the read/write execution rule and the prefix reminder. 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 6-parameter, no-output-schema tool with 83% schema coverage, the description covers the critical operational details: credential handling, read vs write execution, and approval semantics. Minor gap is the absence of any note on result shape or row limits.

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 already 83%, so nearly every parameter is self-documenting, including 'why' and 'approval_id'. The description adds only the reminder about the table prefix, which is marginal value on top of 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 and resource ('Run one SQL statement on a site's database') and bounds the scope to a single statement. It is clearly distinguishable from siblings like db_dump, db_restore, and list_sites.

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?

Explains when the call runs immediately (SELECT/SHOW/DESCRIBE/EXPLAIN in a read-only transaction) versus when user approval is required (anything that changes data), and points to list_sites for the table prefix. It does not explicitly contrast with db_dump/db_restore, so it falls short of a full when/when-not routing statement.

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

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

Goes well beyond the destructive/openWorld annotations: it discloses that the current DB is dumped first (before-restore-...) so the restore is self-undoable, that same-name tables are replaced while unmentioned tables persist, that a foreign/newer dump can break the site, and that it runs in the background (follow with job_output). This is unusually rich behavioral 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, then scoped to intent, mechanics, and risks. It is a dense single paragraph that runs long, but nearly every sentence carries operational value; only minor tightening is possible.

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 destructive, non-idempotent restore with no output schema, the description covers destruction scope, reversibility, background execution/follow-up, and file validation. An agent has everything needed to call it safely.

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% (baseline 3), and the description still adds value by clarifying what 'file' accepts — a path as list_dumps shows it, or any .sql/.sql.gz on the server — and cross-references list_dumps/read_file for validating the file. The remaining params are fully covered by the schema.

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

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

States a specific verb and resource ('Load a .sql or .sql.gz dump into a site's database') plus its two primary intents (undoing a bad change, restoring from backup). An agent can distinguish it from db_dump (the inverse) and db_query 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?

Explicitly says when to use it, when not to ('For a few rows or one table, load the dump into a scratch database instead (playbook restore)'), and names the alternatives (list_dumps, read_file). 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?

Goes well beyond the annotations: discloses that each upload REPLACES Google's list, that the tool merges by keeping the 'current' lines, what remove does, that Google has no upload API so the user must upload manually, and that it only works for URL-prefix properties (not Domain properties). It also states the response contents (whole file, added/kept/dropped, upload instructions). No contradiction with readOnlyHint=true, since the server itself performs no remote mutation.

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 paragraph with zero filler sentences and a front-loaded purpose and link, but it is long and would scan better with the when-to-use and merge/replace behavior split into sentences or bullets. Every sentence earns its place, so it stops short of a structure problem.

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 7-parameter tool with no output schema, it covers everything an agent needs: the manual-upload workflow, replace-vs-merge semantics, the property-type restriction, and the fact that the response includes the full file plus upload instructions. Nothing material is left to inference.

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 real meaning: 'domains (whole sites, the usual choice)' flags the default choice, 'single URLs to disavow, full addresses' disambiguates urls, 'current' is explained as the file Google has now whose lines are kept, and remove is described as taking lines back out. It adds nuance beyond the schema, though it does not restate every field.

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 ('Write the disavow file for Google's disavow links tool'), names the exact external artifact it targets, and no sibling tool does anything similar, so it is trivially distinguishable. The follow-on sentence clarifies it produces a file the user uploads manually, removing any ambiguity about what 'write' means here.

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 gives when to use (after a manual action for unnatural links, or links clearly paid for/built in a scheme) and when not to use ('Google already ignores ordinary spam links, so a high spam score alone is not a reason'), plus the alternative behavior Google applies on its own. This is exactly the when/when-not guidance the dimension asks for.

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/non-destructive, so safety is covered. The description adds value beyond that: result ordering ('ordered by estimated traffic'), the 100-keyword cap, and crucially a cost signal ('One lookup from the plan's allowance') that no annotation conveys.

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?

It is a single dense but front-loaded sentence with the core output described first and the competitor/cost caveats trailing. Every clause carries information, though the semicolon-chained structure 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?

With no output schema, the description does the work of explaining return values (keywords plus position, searches, visits, ranking page) and the competitors variant. It is nearly complete for calling the tool, missing only edge details like pagination or default behavior when competitor keywords are absent.

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 high (80%), so the baseline is 3, but the description still adds meaning: it clarifies that competitors=true returns domains sharing the most keywords, and that domain may be the user's site or a competitor. It reinforces the limit ceiling ('up to 100 keywords') beyond the schema's wording.

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

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

The description states a specific verb and resource ('What a domain ranks for in Google') and enumerates the returned fields (position, monthly searches, estimated visits, ranking page). This clearly separates it from keyword-centric siblings like keyword_volume and keyword_ideas, though it doesn't name those siblings outright.

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 when-to-use: 'Ask for a competitor's domain to find keywords the user's site is missing,' and explains the competitors=true variant. No explicit exclusions or named alternatives, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description adds the id-source hint but says nothing about permanence, reversibility, or whether the note can be recreated.

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 front-loaded sentence with the mutation verb first and the parenthetical id source tucked at the end. Nothing is wasted.

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

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

For a one-parameter, no-output-schema tool whose annotations already flag destructiveness, the description is nearly sufficient. The remaining gap is that it never signals whether the deletion is permanent or recoverable.

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 0% for the single 'id' parameter, so the description must carry the burden. It does add the useful fact that the id is found in the overview output, but it never clarifies format or validity beyond the schema's integer type.

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 a saved note') and adds the qualifying condition for deletion. It does not name the inverse sibling save_note or any undo path, so differentiation is left implicit.

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 usable trigger ('that is wrong or no longer true') and tells the agent where the id comes from ('in overview'), which is real routing help. However, there is no explicit when-not guidance and no mention of save_note as the counterpart operation.

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 read-only, idempotent, open-world behavior, and the description adds genuinely new context: the report compares against the prior period, and unreferred AI visits are bucketed as Direct so the agent can caveat the numbers rather than misreport them. It stops short of stating defaults (already in the schema) or limits/pagination, but the caveat is real added value.

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 in the first clause, and the single trailing sentence carries a non-obvious caveat rather than filler. The assistant-name list is longer than strictly necessary but it usefully bounds what counts as an AI assistant.

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 describe the return and it does so thoroughly (metrics, dimension breakdown, landing pages, trend, comparison period). The remaining gap is the two undocumented comparison-date parameters, which is a minor omission for a reporting tool with zero required arguments.

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 60%, with start_date, end_date and property documented in-schema and compare_start_date/compare_end_date left blank. The phrase 'against the period before' gestures at the comparison parameters but does not define their semantics or defaults, so the description only marginally compensates for the uncovered pair. Baseline 3 is appropriate.

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

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

The description names a specific resource (traffic referred by AI assistants) and enumerates the concrete outputs: sessions, users, engagement, key events per assistant, landing pages, and daily trend versus a prior period. It is clearly distinct from ga4_overview or ga4_report by topic, but it never names those siblings so the agent must infer the boundary 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?

There is no when-to-use guidance, no prerequisite (e.g. property selection is only hinted at via the schema), and no reference to the alternative GA4 report tools that cover overlapping traffic data. The description is purely a statement of what is returned, leaving routing 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 this is a safe read-only, idempotent, open-world operation, so the safety profile needs no restating. The description adds the default channel behavior and the period-comparison behavior, which is useful, but does not cover pagination, row limits behavior, or error/empty-result handling.

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 resource and output metrics, then scope defaults, then the sibling pairing. The metric enumeration is long but each item is genuinely informing the agent what it gets back, so nothing is wasted.

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

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

No output schema exists, and the description compensates by naming every returned metric, which is the key completeness need here. Defaults and the comparison period are surfaced. Minor gap: compare_start_date/compare_end_date have no schema descriptions and the description only gestures at 'an earlier period'.

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

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

Schema coverage is 71%, and the schema itself documents limit, channel defaults, date formats, and property. The description's contribution is confirming the organic-search default and the comparison concept, but it adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a concrete resource (landing pages) and enumerates the metrics returned (sessions, engagement rate, bounce rate, key events, revenue), which distinguishes it from ga4_overview and ga4_report. It is clear what the tool produces, though it never explicitly contrasts itself with those siblings.

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 notes the optional single-channel scope (organic search by default) and the earlier-period comparison, which implies when it is useful. However, it offers no explicit when-to-use or when-not-to-use versus ga4_report/overview. The 'pair with gsc_search_analytics' line is a cross-tool relationship, not alternative-selection guidance.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds useful behavior beyond that — every metric is compared "against the period before," and it discloses the channel groupings and the inclusion of AI-assistant traffic — but says nothing about auth/property prerequisites or limits.

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

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

Front-loaded with the core purpose and the guiding "start here" instruction at the end, so the important routing cue is not buried. The single sentence is long and dense with an enumeration of metrics, which costs a little readability but remains purposeful.

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 convey the return surface — and it does thoroughly, listing the summary metrics, the comparison baseline, the daily trend, the channel breakdown, organic share, landing pages, and AI traffic. An agent knows what it will get and when 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% for both parameters (days with default 28, property id/name), so the schema carries the semantics. The description only loosely reinforces the period concept via "against the period before" and adds no syntax or format detail beyond the schema.

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

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

States a concrete resource (GA4 property traffic overview) and enumerates exactly what is returned: sessions, users, engagement rate, daily trend, channel breakdown, landing pages, AI traffic. This distinguishes it from siblings like ga4_report, ga4_landing_pages, and ga4_ai_traffic, which cover narrower slices of the same data.

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

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

"Start here when the user asks how the site is doing" gives a clear entry-point condition for when to reach for this tool first. It does not, however, explicitly name the alternatives for follow-up depth (e.g. ga4_report or ga4_realtime), so the routing guidance is contextual rather than exhaustive.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description goes beyond that by disclosing what the response contains — time zone, currency, retention, conversion setup, and data-freshness signals (sessions yesterday and 7-day) — and by flagging it as the entry point for analytics work.

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 core purpose and the return contents are front-loaded in the first sentence, with the actionable 'call this first' instruction trailing. The enumeration of health-check fields is dense but earns its place given there is no output 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?

With no parameters and no output schema, the description carries the full burden of explaining what comes back, and it does so thoroughly — field list plus data-freshness indicators. Nothing an agent needs in order to invoke 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; 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?

The description names the specific resource (Google Analytics 4 properties the user selected for AskYourStack) and enumerates what each entry contains, so an agent knows this is a discovery/list tool rather than a report. It is clear and concrete, though it does not explicitly contrast itself with its closest sibling gsc_properties or the other ga4_* tools.

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

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

'Call this first for analytics work' gives a clear sequencing cue that tells the agent when to reach for this tool. It stops short of naming alternatives (ga4_overview, ga4_report, ga4_realtime) or stating when NOT to use it, so the routing is implied rather than 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior: the exact 30-minute lookback window and the dimensions returned, which the annotations cannot express. Auth requirements and rate limits are not mentioned, but the marginal gap is small.

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

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

Two sentences with zero filler: the first front-loads what the tool returns and its time window, the second carries the use cases. Nothing is repeated from the title or 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 single-optional-parameter, read-only tool with no output schema, the description discloses the window and the metric dimensions an agent needs to decide to call it. Property resolution is already handled by 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 100% and the single property parameter is fully documented there, including accepted id formats and optionality. The description adds nothing about the parameter, so 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 resource and scope: realtime active users in the last 30 minutes, with named breakdowns (page/screen, country, device, minutes ago). The 30-minute window implicitly separates it from ga4_overview and ga4_report, but no sibling is named explicitly, so the differentiation is inferred rather than stated.

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?

"Use it to check a launch, a campaign or that tracking works after a change" gives concrete, actionable when-to-use context rather than vague guidance. It does not say when this is the wrong choice or point to a non-realtime alternative such as ga4_report for historical 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 declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds that it maps to the Data API's runReport and mentions an optional comparison period, but says nothing about rate limits, quota, auth/property requirements, or result shape, which is a modest addition over structured data.

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

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

Front-loads the core purpose ("Any GA4 report... pick dimensions and metrics") before the examples, and every example carries actionable dimension/metric pairings rather than filler. It is dense and lengthy in a single block, but for a flexible pass-through reporting tool the examples earn their space.

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 10-parameter, flexible tool with no output schema, the description thoroughly covers the input surface (dimensions, metrics, filters, dates, comparison). The main gap is that it never hints at the returned row/column structure, which an agent must infer, but everything needed to invoke it correctly is present.

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

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

Schema coverage is already 80%, so baseline would be 3, but the description adds real value beyond the schema by enumerating common metric names (sessions, totalUsers, engagementRate, keyEvents, transaction...) and example dimension sets, which the schema does not provide. It clarifies the compare_* pair semantically as a comparison period.

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 resource and scope: "Any GA4 report (the Data API's runReport)", with a concrete verb-action of picking dimensions, metrics, filters and dates. The many examples make the tool's identity unmistakable, though it never explicitly names the sibling preset reports (ga4_overview, ga4_landing_pages, ga4_realtime) it contrasts with, leaving differentiation implicit.

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?

Rich usage context via worked examples (newVsReturning, searchTerm, sessionSourceMedium, trends, conversions, e-commerce), which effectively shows when to reach for this generic report. It stops short of explicit when-not/alternative guidance, e.g. not telling the agent to prefer ga4_overview for standard dashboards, so 5 is not warranted.

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, idempotentHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds that the content is a procedure meant for the agent to follow and that some playbooks end in an 'approved plan', hinting at approval workflows, but says nothing about size, structure or that the guide may steer the agent to other tools.

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 purpose is correctly front-loaded in one sentence, but the body is a very large wall of parenthetical mini-essays, only a fraction of which is needed to choose a playbook; much of that detail belongs in the playbook content the agent will fetch next. A single clause per entry would have served selection equally well.

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

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

Given a one-parameter catalog lookup with no output schema, the description supplies a full value legend and a minimal statement of what is returned. It would be more complete if it noted the guide's expected shape (ordered steps, expected approvals) so the agent knows how to act on 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 description coverage is 0% and the single `name` property has no schema-level description, so the description must carry the load — and it does, describing the scope of all 29 allowed values in prose. It stops short of 5 because the enum values themselves are already self-describing strings and no format or matching guidance is added.

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

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

The opening sentence gives a specific verb and resource: a step-by-step guide for a common job, written for the agent to follow. It is immediately distinguishable from siblings like run, whizzy_tools or list_jobs, though it never names a sibling or explicitly states the boundary between fetching a playbook and executing one.

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 per-entry summaries double as scenario triggers (a site is flooded by bots, a site does not answer, a shop needs updating), so the agent can infer which playbook applies to a given situation. There is no explicit 'use this before X' or exclusion against alternatives, 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 this is a read-only, idempotent, open-world, non-destructive operation. The description adds useful behavioural context about what is returned and the prerequisite connection requirement, though it does not discuss edge cases such as no connected accounts.

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 tightly written sentences with no repetition. The resource description comes first, followed by the routing instruction and setup context, so the most important information is front-loaded.

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

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

For a zero-parameter, read-only discovery tool with rich annotations and no output schema, the description provides everything needed: what it returns, why it matters, and when to call it relative to sibling tools.

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

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

The tool has zero parameters, so there is no parameter semantics to explain. The baseline for zero-parameter tools is 4, and the description does not need to compensate 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?

The description clearly identifies the resource as the user's connected GitHub accounts and organisations, including repository installation scope and AI permissions. It also distinguishes this tool from all other gh_ tools by marking it as the starting point.

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

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

It explicitly says "Start here before other gh_ tools," giving a clear sequencing rule and implicit alternative set. The setup note about connecting on the Sites & Apps page adds practical context without ambiguity.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral detail about retrieving jobs, failed steps, and the end of a failed job's log, but it omits permission requirements, pagination behavior, and log truncation specifics. It does not contradict 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?

The description is two tight sentences, front-loaded with the retrieval modes and ending with a concrete use case. There is no wasted text, though the opening noun phrase is slightly less actionable than a verb-led phrasing would be.

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

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

The description is sufficient to understand what the tool returns, including jobs, failed steps, and log tail, but the overlap with gh_actions_run and the undocumented limit parameter leave meaningful gaps for correct invocation. The annotations cover the safety profile, so those aspects are not 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 only 40%, so the description should compensate more. It does clarify that branch and workflow act as filters and that run_id selects a single run with detailed output, but the limit parameter remains undocumented in both the schema and the description.

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

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

The description clearly identifies the resource and two retrieval modes (recent runs with filters vs. a single run via run_id). However, it uses a noun phrase rather than a specific verb and does not differentiate this tool from the sibling gh_actions_run, whose purpose appears to overlap with the single-run mode.

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 one concrete use case: when a build or deploy workflow fails. But it does not explain when to use the list mode versus run_id mode, nor when gh_actions_run would be the better choice, and it provides no explicit exclusions.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false and openWorldHint=true, so safety is covered structurally. The description adds the eligibility constraint (queued/in-progress only) and a consequence warning about half-finished deploys, which is real added value. However, the warning is oblique — it does not say plainly that cancelling mid-deploy leaves the site in an inconsistent state, nor does it mention permissions or whether the cancel can be undone.

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, front-loaded with the action and its eligibility constraint, with no filler. The second sentence is a worthwhile warning but is phrased vaguely enough ('can leave a site half updated') that it costs a reread.

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 only two required parameters, full schema coverage, and annotations that carry the destructive/non-idempotent profile, the description covers what the agent needs to select and invoke the tool. It stops short of stating the post-cancellation state of the run or that the action is irreversible, which would have made it complete.

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

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

Schema description coverage is 100%, so both parameters (repo with its owner/name example, run_id sourced from gh_actions) are already fully documented in the schema. The description only repeats the provenance of run_id that the schema already states. Baseline 3 applies since the schema carries the load.

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

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

States a specific verb and resource ('Cancel a GitHub Actions run') with a state qualifier ('queued or in progress') and points at the source of the identifier ('run_id from gh_actions'). This is enough to distinguish it from list/inspect siblings like gh_actions, but it never contrasts itself with gh_actions_rerun or gh_actions_rerun_failed, which act on the same resource and are the most likely confusion points.

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

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

The description gives a clear precondition for use — the run must be queued or in progress — so the agent knows this is not for completed runs. The closing sentence signals that cancellation carries a cost ('a deploy stopped halfway can leave a site half updated'), which is usage context rather than an alternative-tool routing rule. No explicit when-not or alternative tool 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 destructiveHint=true, openWorldHint=true, and idempotentHint=false; the description adds the crucial consequence the annotations cannot express — 'It runs whatever the workflow does, deploys included' — plus the trigger prerequisite. It does not cover permissions/auth (relevant given gh_accounts exists) or whether repeated calls create duplicate runs, keeping it at 4.

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 and front-loaded: the trigger constraint and parameter meanings come in one sentence, with the risk warning placed last where it reads as a final caution. The first sentence is somewhat run-on, but no sentence 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?

There is no output schema, so the description is the only place an agent could learn what a dispatch returns (run id? URL?) and how to follow up — that information is absent, leaving the agent unable to chain into gh_actions or gh_actions_cancel after firing. Parameter and risk coverage are otherwise adequate for a 4-param 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 description coverage is 100%, so baseline is 3. The description largely restates the schema for workflow, ref, and inputs, with only marginal added value in pointing to gh_actions as the source of workflow ids; the nested inputs object gets no structural elaboration.

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 ('Start a GitHub Actions workflow') and narrows the scope to workflows with a workflow_dispatch trigger, which is exactly what separates this tool from gh_actions, gh_actions_rerun, and gh_actions_cancel. An agent knows what this does and what class of workflow it applies to 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 a real precondition (the workflow must have a workflow_dispatch trigger) and a pre-flight instruction ('check the workflow first'), which is actionable guidance for a risky operation. It stops short of naming an alternative tool or stating outright when not to use it, so it lands just below the top band.

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 flag destructiveHint=true and idempotentHint=false, but the description adds substantive context the annotations cannot: re-running a deploy or publish workflow repeats that side effect, and only finished runs are eligible. That is real consequence-level disclosure, though it doesn't say whether the call blocks until completion.

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

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

Two sentences, the action and its scope front-loaded, followed by the risk caveat. Nothing is padded and no sentence is redundant.

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 two fully documented params, rich annotations and no output schema, the description covers what an agent needs to invoke it. It stops short of saying what happens after the call (async vs blocking, what is returned), 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 coverage is 100% and both parameters are documented in the schema, so the baseline applies. The description's 'by run_id from gh_actions' merely restates the schema's own 'The run's id from gh_actions' and adds no format or constraint detail beyond it.

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

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

States a specific verb (run ... again) and resource (all jobs of a finished GitHub Actions run) with the scoping qualifier 'all the jobs'. That implicitly distinguishes it from the sibling gh_actions_rerun_failed, but the sibling is never named, so an agent still has to infer the split.

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?

'by run_id from gh_actions' and 'check what the workflow does first' imply the prerequisite (obtain the run first, understand consequences), but there is no explicit when-to-use vs gh_actions_rerun_failed, gh_actions_dispatch, or gh_actions_cancel. Usage is inferable 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 declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is carried structurally. The description earns credit for going beyond that with a concrete consequence: 'A failed deploy job that now succeeds changes what is live' — an agent now understands the real-world blast radius, not just a boolean flag. It stops short of mentioning permissions or whether a new run attempt is created.

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: the operation and its scoping are front-loaded, and the second sentence justifies why the destructive behavior matters. Zero 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 only two required, fully documented parameters, no output schema and full annotation coverage, the definition covers what an agent needs to invoke it, plus the live-state consequence. The remaining gap is return behavior — whether a new attempt/run id comes back — which matters for chaining into gh_actions but is unstated.

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 both parameters (repo, run_id) are already documented in the schema, including the 'from gh_actions' provenance for run_id. The description restates that provenance but adds no format, constraint or edge-case detail beyond the schema, so 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 ('Run only the failed jobs of a GitHub Actions run again') with a scope qualifier ('only the failed jobs') that implicitly separates it from gh_actions_rerun, which re-runs the whole run. It never names that sibling outright, so the contrast is inferred rather than explicit.

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?

'by run_id from gh_actions' gives a useful prerequisite breadcrumb (fetch the run first via gh_actions), which is real workflow guidance. However, there is no statement of when to prefer this over gh_actions_rerun, nor any exclusion for in-progress or already-successful runs.

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

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

Annotations already declare the safety profile (not read-only, not destructive, not idempotent, open-world), so the description's added value is the default source branch and the range of valid parents (branch/tag/commit). It omits failure behavior, such as what happens if the branch name already exists, which keeps it from 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?

A single sentence with zero filler, front-loading the action and then the valid sources and default. Nothing redundant.

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 3-parameter mutation with annotations covering safety and no output schema to explain, the description covers the essentials. It leaves the agent guessing about remote vs local branch creation and conflict behavior, which are the only notable gaps.

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

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

Schema coverage is only 33% (only `repo` documented), so the description must compensate, and it does: it explains that the parent can be a branch, tag, or commit and defaults to main. `name` is left implicit as the new branch name and `from`'s exact format is unspecified, so 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 ('Create a branch') and clarifies the accepted parent types (branch, tag, commit) plus the default. It does not distinguish itself from neighboring gh_* tools (gh_commit, gh_pull_create, gh_repo_settings), so it stops 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 description gives no when-to-use context, no prerequisites (e.g. write access to the repo, whether the source branch must already exist), and no pointer to any alternative tool. The only contextual hint is the 'default the main branch' fallback.

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 flag destructive and non-readOnly behavior; the description adds that remove true revokes access and changes require 'change anything' permission, plus default permission push. It does not discuss idempotency or rate limits, but adds useful mutation context beyond 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?

Compact and front-loaded with the no-username listing case, then mutation cases. The dense semicolon structure is efficient but slightly telegraphic.

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 multi-mode destructive tool with no output schema, the description covers modes, permission values, default, and required scope. It omits return details or pending-invitation specifics, but 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 only 25% (only repo is described), so the description carries username/remove/permission semantics: optional username switches list vs mutate, remove true revokes access, and permission enum values with default push are supplied. This compensates strongly for undocumented schema 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 specific verbs and resource: list collaborators and pending invitations, invite, change permission, and remove. The conditional 'without username/with username' distinguishes its modes; it lacks explicit contrast with sibling tools like gh_repo_settings, but the collaborator resource is clear.

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

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

Explicitly maps parameter states to behavior: omit username to list, provide username to invite/change, remove true to revoke access. Covers when to use each branch but gives no when-not guidance or alternative sibling routing.

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

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

Annotations already declare the write/non-destructive/open-world profile, and the description adds real behavioral rules: commits land on non-main branches by default, exceptions apply for AskYourStack-created or empty repos, and a branch is created from `from` when missing. It omits that repeat calls are non-idempotent (new commits each time) and says nothing about the response payload, but the added context is substantive.

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 verb, the file operations, and the branch/PR routing each appear once with no filler. The parenthetical parameter hints slightly break reading flow but earn their space.

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 5-parameter mutation tool with no output schema and no annotations covering returns, the description should say what comes back (commit SHA, branch ref, per-file status) and what happens if one file in the batch fails. Those gaps are notable but the core invocation semantics are covered.

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?

With 60% schema coverage, the description compensates well by explaining the nested file object semantics (base64 for binary, executable true for scripts, delete: true for removal) and branch/from behavior, which the schema barely documents. It adds no detail on `message` or `repo` formatting beyond the schema, hence 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 ('Commit up to 100 files in one commit') and enumerates the two operations (add/change via {path, content}, delete via {path, delete: true}). An agent can distinguish this from gh_commits (log reading) or git_push 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?

Explicitly routes the post-commit step to gh_pull_create and explains the branch-creation rule via `from`. The caveat is the unexplained phrase 'In the default mode', which implies an alternate mode that is never described, leaving a decision gap.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuine value by stating that comparisons return changed files and their diffs, but it says nothing about pagination (the limit parameter), rate limits, or how large diffs are handled.

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; each parenthetical clause earns its place by tying a parameter to a behavior. The density is high but still readable, with only minor loss from not breaking the three modes apart.

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 seven-parameter tool with no output schema and low schema coverage, the description is adequate on mode selection and output shape ('changed files and their diffs'). It is incomplete on result limits/pagination and on the repo format, so it falls short of fully self-sufficient.

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 14% (repo alone), so the description carries most of the burden: it correctly maps sha, base, head, branch and path to their roles. It leaves limit and repo unexplained in the description, so two of seven parameters have no textual semantics anywhere in the description.

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

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

The description enumerates three concrete operations (list commits, show one commit with changes, compare base..head) with their key parameters, so the scope is unmistakable. It does not explicitly distinguish itself from the close sibling gh_commit, leaving the deduplication for the agent to infer from the wording.

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 parenthetical groupings (branch/path, sha, base and head) effectively tell the agent which parameter selects which mode, which is useful implied routing. However, there is no explicit when-to-use/when-not-to-use guidance or reference to alternatives such as gh_commit or gh_branch, so the agent must guess at the boundary.

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=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), and the description adds meaningful defaults not in annotations: private-by-default, auto_init defaulting to true with a README, and the elevated-mode requirement for public repos. Minor gap on failure modes and what happens on name collision.

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, front-loaded sentences with no filler; the private default and the mode prerequisite come early. The final sentence about later commits on main in default mode is loosely worded and adds less value than the space it takes.

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 8-parameter mutation with no output schema and near-zero schema descriptions, the description covers defaults and the public-mode prerequisite but leaves several parameters and the return/result shape unaddressed. Adequate but not complete for this complexity.

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

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

Schema description coverage is only 13%, so the description has to carry the load, and it does explain private, auto_init, and gitignore_template naming along with the owner scope. However, homepage, description, license_template, and name format/constraints get no treatment in either place.

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 (create a repository) plus its scope (user account or an installed organisation), which cleanly separates it from read/management siblings such as gh_repo, gh_repos, and gh_repo_settings. An agent can identify the operation 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?

Provides real selection context: public creation requires the 'change anything' mode, and the target must be an account/organisation where the app is installed. It does not explicitly name when to prefer a sibling (e.g. gh_repo_settings for editing an existing repo), so no full exclusion guidance.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond repeating schema property names: it does not warn that retries create duplicate issues (non-idempotent), does not mention required permissions, and does not say what happens when labels or assignees do not exist.

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 short sentence with no filler and the core action front-loaded. It is lean, though its brevity comes at the cost of the missing detail noted elsewhere rather than through efficient prioritization.

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?

This is a non-idempotent write tool with no output schema and mostly undocumented parameters, yet the description never covers authentication, required fields, duplicate-risk on retry, or what the response contains (issue number/URL). For a mutation tool in a large sibling set, that leaves the agent under-equipped.

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 20% (only 'repo' is documented, with the owner/name format). The description merely lists 'title, body, labels and assignees' without adding format details — e.g. whether assignees are GitHub usernames, whether labels must already exist, or title length constraints — so it does not 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?

The description states a specific verb and resource ('Open an issue') and enumerates the settable fields, which clearly separates it from gh_issue_update and gh_issues. It stops short of explicitly naming sibling alternatives, so a 4 rather than 5.

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

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

There is no guidance on when to use this tool versus gh_issue_update (to modify an existing issue) or gh_issues (to read them), and no prerequisites such as repo access or authentication. The agent must infer usage entirely from the name.

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 read-only, idempotent, non-destructive, open-world behavior. The description adds useful behavior beyond that: listing supports state/labels filters, and fetching by number returns the issue with comments. It does not cover auth needs, rate limits, pagination, or 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?

The description is a single short sentence with no filler. It is front-loaded with the main operation and efficiently signals the two usage modes.

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 five-parameter tool with low schema coverage and no output schema, the description is too sparse. It does not explain limit/pagination, output shape, filtering details, or authentication expectations, leaving important context 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 20%, so the description must carry more parameter meaning. It references state, labels, and number in a useful mode-switching way, but does not explain limit, labels format, state enum behavior, or how number changes the response beyond including comments.

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

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

The description states a clear verb and resource: list issues, or fetch one issue with comments. It also distinguishes the bulk/list mode from the single-issue mode via the parenthetical cues. It is not maximally specific about GitHub context or sibling differentiation, but an agent can identify the operation.

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: use state and labels to list issues, or number to fetch one issue with comments. There is no explicit when-not guidance or reference to alternatives such as gh_issue_create or gh_issue_update. The mode selection is helpful but alternatives are left to inference.

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