Blawgy

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

Discloses behavior far beyond the annotations: the duplicate-intent guard and its `blocked` response, the `force: true` override, posts-per-week slot consumption, refresh-suggestion handling that instead starts a smart-update draft, the review-always rule under Updates autopilot, and the specific `not-managed`/`refresh-not-ready` blocked cases where nothing is added.

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 first sentence is well front-loaded, but the second is a dense multi-clause run-on covering numerous branching cases with no bullets or structure. The content is largely substantive, yet the formatting makes it hard to parse quickly.

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 tool with no output schema, the description documents return shapes across the important branches (`refresh` with updateId or briefReady, and the blocked reasons). An agent has enough to call it and interpret the result.

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

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

Schema coverage is only 25% (only `site` is documented), so the description must compensate. It does: `scheduledDate` is explained as the fallback date, `force` is defined as overriding the duplicate-intent guard, and `suggestionId` is tied to the plan's suggestions list.

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: 'Turn one of the plan's suggestions ... into a real scheduled entry,' and points at get_plan `suggestions` as the source. This distinguishes it cleanly from siblings like add_to_plan, dismiss_plan_suggestion, and update_plan_entry.

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 rich conditional routing (fresh vs refresh suggestions, managed vs not-managed pages) and names downstream tools (approve_update, get_refresh_brief, mark_refresh_done). However, it never explicitly contrasts when to choose this over add_to_plan or dismiss_plan_suggestion.

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, destructiveHint=false, idempotentHint=false, and openWorldHint=false, covering the safety profile. The description adds one behavioral detail — 'The first one becomes primary' — but omits permissions, duplicate handling, and what the call returns. With annotations doing the heavy lifting, this is adequate but thin.

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 and efficient: purpose, primary-location side effect, then the minimum requirement, then the accepted keys. The key list is long but directly useful for callers; no filler sentences.

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 tool takes a nested profile object and has no output schema, so the description should carry more of the contract. It covers purpose, the primary side effect, and the city/address rule, but omits the required `site` argument, duplicate behavior, and any return-value expectations.

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%, and the description lists all accepted profile keys, largely duplicating the schema's property names while also adding a real cross-field rule: 'Give at least a city or an address.' It never mentions the required top-level `site` parameter or explains most nested fields, so it only partly compensates 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 ('Saves a new business location') and adds that the first location becomes primary. It implies creation rather than update, which distinguishes it from update_business_location, but it never names an alternative or explicitly separates itself from a sibling like set_primary_location.

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

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

No when-to-use guidance, no alternatives, and no prerequisites are given. The only instruction is a data requirement ('Give at least a city or an address'), which is validation rather than routing. An agent gets no help choosing this over update_business_location or set_primary_location.

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 (readOnlyHint=false, idempotentHint=false, destructiveHint=false) by disclosing non-obvious behaviors: duplicates are silently ignored, saving queues an async lookup of volume/difficulty/coverage, and new entries show 'researching' in list_my_keywords for minutes. This is exactly the async-state context an agent needs and cannot get from the schema.

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

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

Four tight sentences that are front-loaded with the core purpose, then layered with duplicate handling, async status, and activation timing. Every sentence contributes information an agent would otherwise have to discover empirically.

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 mutation tool with annotations carrying the safety profile and no output schema, the description covers the essential unknowns: what is mutated, dedup behavior, the asynchronous side effect, where to observe it (list_my_keywords), and how to trigger downstream use (generate_plan). Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (site and keywords, including the 100-item cap and 200-char limit). The description adds no syntax or format guidance for either parameter, 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 and resource ('Adds keywords to the customer's own list') and even anchors it to the UI location (Settings > Keywords), which disambiguates it from the many other keyword tools in the sibling list. An agent can immediately tell this adds to a personal keyword list rather than saving a research set or excluding keywords.

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's free, the planner picks entries up on its next refill, and the agent can call generate_plan to force the update sooner. It does not explicitly contrast with save_keywords or state when not to use it, so it falls short of the 5-level 'when/when-not/alternatives' 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 readOnly=false, destructive=false, idempotent=false and openWorld=false, so the safety profile is covered. The description usefully adds the downstream consequence (the product becomes mentionable/linkable in articles) and the manual-only scope, but it says nothing about what happens if the product already exists, despite idempotentHint=false implying duplicate risk.

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: capability and required inputs come first, then the exclusion. Nothing is padded or repeated from structured fields beyond the required-fields reminder.

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 non-idempotent mutation with no output schema, the description covers purpose, required inputs and the key alternative path. The remaining gap is the undocumented optional parameters and the duplicate-creation behavior, but the core call decision is supportable.

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 2 of 9 parameters (site, image) have schema descriptions (22% coverage), so the description must compensate — instead it only restates that name and description are required, which the schema already marks as required. url, tags, price, currency and productType are undocumented in both places, so an agent gets no guidance on the optional fields.

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

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

States a specific verb and resource ("Adds a manual product") plus the effect that matters downstream ("so articles can mention and link to it"). It also carves itself away from the automatic catalogue path, so an agent can distinguish it from sync_products/get_product 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 says when NOT to use it (Shopify or Dutchie catalogues, which sync automatically), which is the main ambiguity for product creation. It doesn't name the sibling to use in that case (e.g. sync_products / get_product_sync_status) or clarify add_ vs update_product, so it stops just short of full 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 only declare it is a non-read-only, non-idempotent, non-destructive, closed-world write. The description goes well beyond that: placement on the next open cadence slot, the exact `blocked: "intent-owned"` / `blocked: "excluded"` response semantics, `coveredBy` reporting, queued status with kind `plan_topic_add`, and the side effect that entries count against the site's posts-per-week quota.

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 keyword/cluster decision, then the blocking and async behaviors. Dense and largely waste-free, though the later sentences are long and pack several distinct behaviors (blocked codes, queued polling, quota effect) into single run-on statements.

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 by documenting the relevant response shapes: blocked outcomes with owning page/coveredBy, and the queued/plan_topic_add status with the recommended poll. For a 9-parameter mutation tool, this is complete enough to call 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%; the description adds real meaning for `keyword` vs `cluster` (mutually exclusive, one-article vs multi-article), `scheduledDate` (default is next open slot), `force` (override intent ownership) and `title` (keyword adds only). It does not address `intent`, `difficulty` or `searchVolume`, which have no schema descriptions either, so it does not fully close 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?

Opens with a specific verb+resource ('Add an article to the plan') and immediately distinguishes the two add paths (one article by `keyword`, several by `cluster`), which separates it from siblings such as add_my_keywords, update_plan_entry or generate_plan. An agent can identify what this tool produces without opening the schema.

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

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

Gives explicit routing: use EITHER `keyword` OR `cluster`, with a note that cluster labels come from get_keywords, and names get_job as the polling tool for queued adds. It also states the when-blocked conditions and the `force: true` escape hatch, so the agent knows both when to call it and what to do on failure.

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

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

Annotations only declare the generic safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description adds the traits that actually matter: no data is saved, it consumes a few LLM calls, it takes 15-40 seconds, the preview option adds ~1 minute and DataForSEO spend, and it fails on already-registered or social/platform domains. The readOnlyHint=false flag is consistent with the disclosed side effects (spend, LLM calls) rather than a data 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?

Front-loads the tool's role ('Step 1 of adding a site'), then returns, then cost/latency, then failure conditions, then the follow-up call. Every sentence carries new information with no padding.

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, but the description enumerates the returned artifacts (business description, audience and tone options, competitor domains, business type, search market, locations), covers cost, latency, and failure modes, and names the successor tool. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description nonetheless adds quantified meaning to includeKeywordPreview (about a minute of extra time plus DataForSEO spend) beyond the schema's vague 'slow, spends credits', though it says nothing extra about the domain or the description override parameter.

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 ('Crawls a domain that is not yet set up'), positions itself as 'Step 1 of adding a site to Blawgy', and enumerates exactly what it returns. It is clearly distinguishable from the sibling create_site, which it names.

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 workflow guidance ('Review or edit the suggestions, then call create_site'), explicit failure conditions (domain already registered, or a social/platform site), and a conditional for the optional preview parameter. When-to-use, when-not-to-use, and the next step are all present.

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 non-idempotence, but the description adds genuinely new behavioral context: the previous image is retained for undo, the CMS push affects only the featured image, and the first call is non-mutating and returns a summary plus confirmToken. It stops short of covering token expiry, permission requirements, or failure 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, front-loaded with the action and followed by consequence, undo path, and the confirmation flow. Every sentence carries information, though the confirmation mechanics could be compressed into the schema-referenced field.

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 4-parameter mutation with no output schema, the description covers the key agent needs: what changes, what is preserved, how to reverse it, and that a two-step confirm gate exists. It omits error/edge behavior and the content of the summary, which keeps it from being fully 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 only 50% (site and confirmToken are documented; postId and candidateId are bare strings). The description partially compensates by implying candidateId is a generated/uploaded candidate and postId is a post already on the CMS, but it adds no format, ID-source, or selection detail beyond that inference.

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 first sentence names a concrete verb (makes one candidate the post's image) plus the resource and the CMS side effect, which cleanly separates it from siblings like upload_post_image, get_post_image, and get_photo_candidates. It also states the scope restriction (image only, text untouched).

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 routes the agent: use revert_post_image to undo, and it explains the required two-call confirmation sequence with confirmToken. It does not explicitly state prerequisites (e.g. that a candidate must first exist from get_photo_candidates) or when not to use it, so it falls short of a full when/when-not guidance.

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

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

Adds substantial context beyond the annotations: the previous version is retained for revert_update, a 60-day quiet period follows, evaluation is split between search and content parts with automatic per-part revert, and the call is public and immediate. It also discloses the confirmToken summary-then-confirm protocol, which is the operational behavior an agent most 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?

Front-loads the core action and consequence, then the confirmation protocol. The middle passage on per-part judgment metrics is dense but earns its place by explaining what happens after publishing; minor tightening possible but no filler.

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

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

With no output schema, the description supplies what the first call returns (a summary and token), the eventual outcome (auto-revert of worse-performing parts), and the irreversibility/visibility profile. That is sufficient for a destructive, non-idempotent 3-parameter tool.

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

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

Schema coverage is 67%; site and confirmToken are documented in the schema, and the description reinforces the confirmToken semantics ('first call returns a summary and a confirmToken; call again with confirmToken to proceed'). updateId remains undocumented in both places, but the description meaningfully adds to the confirmation parameter.

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 ('Publish a ready update draft to the live page'), plus the scope constraint that it applies to update drafts rather than articles or location pages. An agent can distinguish this from publish_draft or publish_article_from_builder by the resource named.

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

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

Gives an explicit prerequisite ('Read the draft first' via list_update_opportunities with includeHtml or draft_update's result) and describes the two-step confirm flow. It does not explicitly exclude adjacent publishing siblings, but the read-first requirement and draft precondition are clear context for use.

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?

Discloses latency ('slow, up to a minute'), side-effect scope ('only proposes; nothing is written or published'), return contents, and plan gating — well beyond the annotations. There is mild tension with readOnlyHint=false, but the write happens to detection state rather than published content, so it reads as clarification rather than contradiction.

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 action, then side effects, then cost and eligibility. No filler and every clause carries decision-relevant 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?

No output schema exists, but the description states what is returned ('the detection summary and the refreshed list'), plus timing, side effects, and access requirements. Nothing an agent needs to call this safely 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% and the single 'site' parameter is fully documented, including the allowed value. The description adds nothing about the parameter, so the baseline of 3 for a well-covered schema 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 concrete verb and resource ('Re-run update detection') plus the data source (latest Search Console data), and contrasts it with the automatic weekly run and autopilot path. An agent can distinguish it from list_update_opportunities or get_updates_overview 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?

Clearly says when to use it (you want detection refreshed right now) and implicitly when not (the weekly run already does this; autopilot also writes and publishes). It adds the Pro+/grandfathered eligibility constraint, though it does not name a specific sibling to call instead for merely reading opportunities.

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 disclosing that plan generation blocks 30-90 seconds, that missing keyword research is kicked off in the background, that the plan self-fills within minutes, and the exact polling sequence (get_job kind=research, then get_plan). This timing and async behavior is exactly the context annotations cannot express.

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

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

Front-loads the sequence position and optional settings, then layers the timing caveat and the background-research workflow. Every sentence carries actionable information with no filler.

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

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

With no output schema, the description still explains what completion produces (a first content plan), how long it takes, and how to observe the result via polling. That is sufficient for an agent to call it correctly and follow up.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning for draftMode (articles land as CMS drafts for review instead of publishing) and mentions posts-per-week cadence. horizonWeeks is left to the schema, so it is not fully additive.

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 operation (finish site setup: set draft mode and posts-per-week, then generate the first content plan) with clear framing as step 3 in a sequence. An agent can distinguish it from siblings like create_site and generate_plan 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?

Explicitly says when to use it (step 3 of adding a site), that re-running is acceptable, and names the prerequisite tool (create_site). It also routes the agent to get_job and get_plan for the async follow-up, so little 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 flag this as a non-read-only, non-destructive, non-idempotent write, and the description adds real behavior beyond that: the key never expires, Blawgy subsequently submits the sitemap and every new article, and the failure shape (a list of verified properties) tells the agent how to recover via bingSite.

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 front-loaded sentences with no filler; the parenthetical key-location instructions are dense but earn their place by removing a lookup step. Slightly run-on toward the end.

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 burden and largely does so: it covers prerequisites, side effects (sitemap/article submission), and the error/retry contract. Missing only auth scope or rate-limit notes.

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. The description adds genuine meaning by explaining the bingSite parameter's role as a retry handle derived from a prior attempt's sites list, connecting it to the failure mode rather than just restating 'exact Bing property URL'.

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 ('Connects Bing with the owner's Bing Webmaster API key') and is clearly separable from siblings like connect_gsc, connect_dutchie, and connect_platform by the Bing-specific credential.

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 the prerequisite ('the site must already be added and verified in Bing') and the recovery path when the key sees zero or multiple verified properties. It does not explicitly contrast with connect_gsc or state when not to use it, so it stops short of 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 write status, non-destructiveness, and non-idempotency. The description adds meaningful behavioral context beyond that: the API key is stored write-only and never returned, and the first menu pull is slow. It does not mention failure modes or permission requirements, but the added security and performance details make it genuinely helpful.

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 compact sentences are front-loaded with the core action, then security behavior, then a latency caveat. Every sentence carries distinct, useful information without repetition or 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 write-connect tool with no output schema, the description covers purpose, key handling, and performance well, while annotations already declare the safety profile. It leaves out failure behavior and whether an existing connection is replaced, but it is otherwise complete enough to call correctly.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description does not add syntax or meaning beyond what the schema provides for site, label, or apiKey, which is acceptable at this coverage level but not enriching.

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 action (verifies a Dutchie API key, attaches its store location, pulls the live menu) and the resource (Dutchie location). It distinguishes this tool from related siblings like sync_dutchie and get_dutchie_status through the initial-connect wording, but it does not explicitly name or compare those alternatives.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative sibling tools are named. The latency note '(first menu pull)' is a useful caveat but not a usage guideline. An agent must infer from the name that this is for initial setup rather than ongoing syncing.

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

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

Goes well beyond the annotations: it discloses that the saved connection is replaced (so future articles publish to the new CMS), that credentials are never returned, and that the operation is a two-step confirm flow where the first call returns a summary plus confirmToken. The destructiveHint annotation only flags risk generically; the description explains the exact effect and the confirmation protocol.

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

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

A single dense paragraph, but it is front-loaded with purpose and every sentence carries operational weight (platform credential matrix, replace semantics, credential handling, confirm flow, follow-up call). Only the 'exactly like the Settings page' clause is mild 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 19-parameter mutation tool with no output schema, the description covers the essentials: platform-specific inputs, destructive replacement behavior, the two-step confirmation, and the next tool to call. It does not describe what the first-call summary contains or how to recover from a failed credential test, which are the only remaining 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?

With 19 params at 58% schema coverage, the description does real work by mapping credential sets to platforms (WordPress username+app password, Webflow token+collection id, Shopify store name+token or client id/secret+optional blog id, Wix site id+API key, Framer project URL+API key, Duda site name+optional user/password). This lets an agent select the right subset, though the mapping is prose rather than named parameters, so the agent must still infer exact field names.

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 (tests/saves CMS credentials) and enumerates the six supported platforms, which cleanly separates it from the other connect_* siblings (connect_bing, connect_dutchie). An agent immediately knows this is the CMS-connection tool rather than a search or status tool.

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 usage context: call it to connect or re-test a CMS, and explicitly name get_platform_options as the required follow-up when a blog/collection/member must be chosen. It does not, however, state when NOT to use it (e.g. vs. the platform-specific connect_bing/connect_dutchie tools), leaving that 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 a non-read-only, non-destructive, non-idempotent create, so the safety profile is covered. The description adds the genuinely useful two-step fact that guardrails live in a library and must be attached separately, but says nothing about name collisions, duplicate creation, or whether `enabled` defaults on.

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 core action front-loaded and the workflow hint second. No filler, no restatement 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 a 4-parameter mutation tool with 25% schema coverage and no output schema, the description covers the concept but omits defaults (`enabled`), uniqueness behavior for `name`, and what is returned. Adequate but with clear holes an agent would have to guess around.

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 schema coverage at only 25%, the description must compensate, and it partially does by mapping 'named' and 'writing rules' to the name and rules parameters. It never addresses `enabled` or why `site` is required on a library-scoped resource, leaving gaps the schema cannot fill.

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 ('Adds a named set of writing rules to the library') and clarifies what a guardrail actually is, which the bare name does not convey. An agent can distinguish this from list_guardrails, update_guardrail, and delete_guardrail 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?

Names update_site_guardrails as the follow-up step, which is real workflow routing, so the agent knows creating alone does not apply the guardrail anywhere. It stops short of explicit when-not guidance (e.g. use update_guardrail to modify an existing one).

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 past the annotations by describing what actually happens: the first call returns only a summary and confirmToken (consistent with destructiveHint=true), the second commits; billing outcomes differ by account type; the response carries a Stripe checkout URL and the site key; cross-account domains fail with 409.

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 workflow role and the core action, and nearly every clause carries unique operational detail. It is nonetheless a single dense block covering workflow, billing, scoping, error codes and confirmation semantics — splitting it into short labeled sections would cost bandwidth but improve scannability.

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 13-parameter mutation with nested objects and no output schema, the description covers the return value (site key plus billing state/applicable link), the confirmation protocol, credential scoping, and the expected error — nothing an agent needs before invoking it is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds governing rules the schema cannot express — that plan and billingPeriod must be passed together, that clientId comes from create_client/list_clients and requires partner scope, and that plan/billingPeriod are rejected in client mode. The enumerated `market` and `businessProfile` keys largely restate 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?

The opening clause names a specific verb and resource — "registers the domain under the caller's account" — and immediately distinguishes it from siblings by labeling it "Step 2 of adding a site," with analyze_new_site supplying inputs and complete_site_setup as the follow-up.

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 sequencing (values "usually from analyze_new_site, edited as needed"; "Then call complete_site_setup"), plus scoped alternatives: clientId only for white-label partners on partner-scoped credentials, plan/billingPeriod only for direct customers and refused otherwise. The 409 condition tells the agent when this call is the wrong one.

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 disclosing that the signing auth token is returned only ONCE and must be stored, and by detailing the two-step destructive confirmation flow with confirmToken. This is critical operational context an agent cannot infer from destructiveHint alone.

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

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

Three tight sentences, front-loaded with what the tool does, followed by the one-time token warning and the confirmation flow. No filler and nothing important buried.

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 mutation tool with no output schema, the description covers the essential behaviors (event delivery, one-time token, destructive confirm flow). The main gap is undocumented parameters, which is captured under parameter semantics rather than here.

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 29%, so the description must compensate. It adds a meaningful constraint for webhookUrl ('public https URL') and reiterates the events enum, but leaves site, name, validity, and maxRetries completely undocumented in both schema and 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?

States a specific verb (Registers) and resource (a public https URL to receive article events) and enumerates the exact event types it will deliver. This clearly distinguishes it from sibling webhook tools like list_webhooks, update_webhook, delete_webhook, test_webhook, and regenerate_webhook_token.

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 explains the two-step confirmation invocation flow (first call returns summary + confirmToken, second call with confirmToken proceeds), which is genuine usage guidance. However, it never says when to prefer this over alternatives or prerequisites (e.g., use test_webhook to validate, or list_webhooks first), leaving sibling routing implicit.

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, but the description adds substantial context beyond them: the delete is soft (plan/list removal, cancellation of a queued write), it cannot be undone from here, and the destructive flow requires a two-call confirmToken sequence. This is exactly the behavioral detail annotations cannot carry.

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

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

The core action is front-loaded in the first clause, and each subsequent sentence adds a distinct, decision-relevant fact (soft-delete semantics, CMS boundary, irreversibility, confirm flow). No filler or restatement 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?

With no output schema, the description steps in to explain what the first call returns (a summary and a confirmToken). Combined with the soft-delete scope, irreversibility, and CMS exclusion, an agent has everything needed to invoke this 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 description coverage is 67%; site carries its enum inline and confirmToken is documented in the schema, and the description reinforces the confirmToken flow. However, the id parameter has no description in either the schema or the description, so the description does not fully compensate for the coverage gap. 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 (remove/delete) and resource (article) and immediately scopes it: soft delete, disappears from the plan and lists, queued write cancelled. It also draws a sharp boundary against the sibling delete_builder_draft/CMS workflow by clarifying it does NOT remove an already-published post. An agent can identify the action without opening the schema.

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

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

Gives explicit when-to-use (removing an article from Blawgy) and when-not-to-use (published post on the website, which must be deleted in the CMS), naming the alternative venue. It also tells the agent the exact two-step invocation path via confirmToken, so the agent knows how to proceed.

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 meaningful behavior beyond the annotations: permanence/irreversibility, the side-effect boundary (saved articles are not affected), and the confirm-token safety flow. The annotation merely flags destructiveHint=true; the description explains how destruction is gated and what survives.

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 purpose and irreversible scope before the procedural detail. 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?

No output schema exists, and the description already discloses what the first call returns (summary and confirmToken). For a destructive, two-step tool this covers everything an agent needs 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 67%; the description explains the confirmToken parameter's role (first call obtains it, second call proceeds) beyond the schema's terse wording, compensating for the undocumented draftId. site and draftId are largely left to 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 (permanently delete) and specific resource (Article Builder draft), and the note that saved articles are unaffected disambiguates it from the sibling delete_article. An agent can select it correctly 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?

Clearly instructs on the two-step invocation: first call returns summary+confirmToken, second call passes confirmToken. This is solid usage context, but it does not explicitly name when to prefer this over alternatives like delete_article or publish_draft.

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 covered. The description adds genuinely new context: the blast-radius constraint ("Pages already generated are not touched") and the two-phase confirm-token protocol that explains why repeated calls behave differently. It stops short of stating reversibility or required permissions/role.

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 terse sentences, each earning its place: purpose first, then side-effect scope, then the destructive confirmation protocol. No filler and no 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 a destructive, no-output-schema tool, the description covers the essentials an agent needs: what it destroys, what it leaves intact, and the confirm flow. Missing auth/permission requirements and whether the deletion is reversible, but the core call path is 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%; site and confirmToken are documented in the schema, while locationId has no description anywhere. The description adds no parameter-level meaning beyond restating the confirm flow already present in the confirmToken schema description, which is 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 and resource ("Removes a saved location") that an agent can act on immediately. It is clear in isolation, but it doesn't name the boundary against near-neighbors like remove_dutchie_location, delete_site, or update_business_location, so disambiguation still requires 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?

Usage is implied rather than stated: you call it to delete a business location. The description does give the two-step invocation flow, which is procedural guidance, but it offers no explicit when-to-use/when-not-to-use conditions or routing to alternatives such as update_business_location when deletion is not what the user meant.

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, but the description adds the critical two-step confirmation flow and the cascading effect (detaches from every site), which an agent would otherwise miss. It partially overlaps the confirmToken schema description, but the blast-radius detail is unique and valuable.

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 action and scope, then the destructive/confirmation caveat. No filler, and the most surprising information (the token handshake) is not buried.

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, but the description explains the confirm flow's return (a summary plus token), the mutation's cascade, and the required args are in-schema. An agent has everything needed to invoke it correctly across two calls.

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%: 'site' and 'confirmToken' are documented in-schema, while 'guardrailId' has no description anywhere. The description adds no format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

Specific verb + resource: 'Removes a guardrail from the library and detaches it from every site.' This distinguishes it from adjacent operations like update_guardrail, list_guardrails, and get_site_guardrails, and even clarifies the scope of removal (library-wide plus per-site detachment).

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 confirmation workflow ('call again with confirmToken') is procedural guidance, but the description never says when to prefer this over update_guardrail or when deletion is inappropriate. Usage is only implied by the tool's name and purpose.

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 the description adds real context beyond them: irreversibility ('Cannot be undone'), the cascading deletion of the in-use photo and angles, and the first-call-returns-token workflow. That is exactly the behavioral detail an agent needs before invoking a destructive operation.

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 compact sentences, front-loaded with the action and scope, then the irreversibility warning, then the confirmation mechanic. No filler and no repetition.

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, no-output-schema tool, the description covers destruction scope, irreversibility, and the token workflow, which is most of what is needed. It could note that the confirmation summary precedes actual deletion of all listed assets, but the gap is minor.

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%, so confirmToken and site are already documented in the schema; the description's confirmToken mention largely repeats the schema text. photoId carries no description in either place, and the description adds no format or constraint detail, so a baseline 3 is appropriate.

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

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

States a specific verb and resource ('Removes a product photo ... from the bank') and clarifies the cascading scope (in-use photo and angles), which distinguishes it from generic delete_* siblings. It stops short of naming an alternative such as duplicate_photo or restore_photo_original, so sibling differentiation is only partial.

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 explains the two-step confirmation flow ('call again with confirmToken to proceed'), which is genuine usage guidance, but it never states when to prefer this over relatives like delete_product or update_photo, nor when not to use it. Usage is implied rather than explicitly routed.

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, but the description adds genuinely non-derivable behavior: irreversibility (no un-archive in the dashboard) and the two-step confirmation protocol where the first call returns a summary plus confirmToken and the second call proceeds. That is exactly the extra context an agent needs before invoking a destructive tool.

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

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

Three sentences, each earning its place: effect first, then the safer alternative, then the destructive confirmation mechanics. Front-loaded and waste-free.

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 explains what the first call returns (a summary and confirmToken), covers reversibility, and names the alternative tool. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 67% and confirmToken is already documented in the schema, but the description adds the flow semantics the schema lacks: the token comes from a prior call with the same arguments and is omitted on the first call. productId remains undocumented in both places, which keeps this below 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 (archives), the resource (the product), and the observable effect (disappears from the catalogue and from articles). It also names the sibling hide_product as the softer alternative, 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 an explicit routing rule: prefer hide_product when unsure, which covers the main ambiguity against the sibling tool. It stops short of stating hard when-not conditions (e.g. products referenced by published articles), so it is strong context rather than a complete decision rule.

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 substantial context beyond the destructiveHint annotation: soft delete semantics, immediate disappearance from the dashboard and list_sites, article publishing stops, subscription cancels at end of billing period with comped sites deactivated at once. It also discloses irreversibility from the API and the two-phase confirmToken handshake.

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

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

A single dense paragraph that leads with what is destroyed and follows with permissions, partner behavior, and the confirmation flow. Every clause carries information, though the subscription/comped-site detail could be tightened slightly.

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 explains what the first call returns (a summary and confirmToken) and what state results after confirmation. For a destructive, non-idempotent operation, nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real workflow meaning: the first call with no confirmToken returns a summary and token, and the second call proceeds. That is more than a restatement of the schema's confirmToken text and clarifies the required call sequence.

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 ("Removes a site from the account") and immediately scopes the meaning of removal as a soft delete that removes it from list_sites. This separates it cleanly from delete_article, delete_product, and the other delete_* 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?

Gives clear preconditions (only the site owner; invited teammates cannot; white-label partners may delete a client's site) and the escape hatch for reversal (contact support). It does not name an alternative tool for the non-owner case, so it stops just short of explicit when-not-and-use-instead 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 destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: deliveries stop, and the operation is gated by a confirmation token, which tells the agent the first call is non-terminal and safe to inspect.

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, and the destructive nature plus the confirmation flow are front-loaded. Nothing is padded or restated unnecessarily.

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 correctly explains what the first call returns (a summary and a confirmToken). It stops short of describing the final response or whether deletion is reversible, which would fully close the loop for a destructive operation.

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

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

Schema description coverage is 67% (site and confirmToken documented, webhookId undocumented). The description restates the confirmToken flow but adds no syntax or format detail beyond the schema; webhookId remains undocumented in both places, so 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 ('Removes the webhook') plus the concrete effect ('stops all deliveries to it'), which is more than the name alone conveys. An agent can distinguish this from the many other delete_* siblings (delete_article, delete_site, delete_product) purely from the description.

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 procedural guidance for the two-phase flow: first call without confirmToken to get a summary and token, second call with confirmToken to proceed. It does not name an alternative tool or state when to prefer update_webhook over deletion, but the invocation sequence 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?

Adds real behavioral context beyond the annotations: scope is limited to the homepage, results are not persisted, and the call is slow due to a page scrape — a useful latency warning no annotation conveys. The only tension is that readOnlyHint=false is conservative relative to 'Nothing is saved', but the description's disclosure is transparent and the mutation is correctly delegated to add_business_location.

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

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

Three short sentences, front-loaded with the operation, then side-effect/routing, then the latency caveat. No sentence is redundant and none restates the tool name.

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

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

With no output schema present, the description must carry the return contract and does so by listing the extracted fields, and it adds persistence, routing, and latency details an agent needs to sequence the call correctly. Nothing material is missing for this single-parameter tool.

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

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

Schema description coverage is 100% for the single 'site' parameter, so the schema already documents it. The description adds the framing that the site is scraped via its homepage but no new parameter syntax or validation detail, which is the expected baseline 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?

Specific verb+resource ('Reads the site's homepage') plus an explicit enumeration of what is returned (business name, address, phone, city). It is clearly distinguishable from siblings list_business_locations and add_business_location, which are named or implied by the routing instruction.

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?

Names the follow-up tool explicitly ('pass the result to add_business_location') and establishes the precondition that nothing is persisted, so the agent knows this is the detection step before a write. It stops short of stating when-not to use it (e.g., when a location already exists), so no exclusions are given.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description adds real behavior on top: what breaks (URL submission halts until reconnect) and the non-obvious two-call confirmation protocol via confirmToken. This is exactly the extra context a mutation tool 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?

Three short sentences, front-loaded with the action and its consequence, then the confirmation mechanics. Every sentence carries information and nothing is padded.

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

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

There is no output schema, but the description covers the return behavior (first call returns a summary and token), the prerequisite for the second call, and the user-visible side effect. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the schema already documents both `site` and `confirmToken`, including the omit-on-first-call rule. The description restates the token flow rather than adding new syntax or constraint detail, so the baseline 3 applies.

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

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

States a specific verb and resource ("Removes the Bing connection") and names the counterpart tool (connect_bing), so an agent can place it against connect_bing and disconnect_gsc without opening a schema. The scope is exact and unambiguous.

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 operational consequence ("Bing URL submission stops") and the recovery path via connect_bing, plus the required two-step confirm flow. It does not explicitly say when one should avoid disconnecting, but the context an agent needs to decide is present.

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 destructiveHint=true annotation, the description discloses the concrete impact (traffic/ranking reports stop) and, crucially, the two-step confirm flow: first call returns a summary and confirmToken, second call proceeds. This is behavioral detail the annotations do not capture and is exactly what an agent needs to avoid an accidental destructive call.

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 no waste, purpose front-loaded, then consequence, then the confirmation protocol. Every sentence earns its place.

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

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

With no output schema, the description usefully explains what the first call returns (summary plus confirmToken). Combined with the annotations and full schema coverage, nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning about how confirmToken is meant to be used across calls ('first call... call again with confirmToken to proceed'), reinforcing the token lifecycle beyond the schema's field 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?

States a specific verb and resource ('Removes the Google Search Console connection') and is immediately distinguishable from the sibling disconnect_bing. It also names the concrete consequence (traffic and ranking reports stop), so the agent knows exactly what the operation affects.

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 when the tool is relevant and names the recovery path via get_connect_link, which is effectively the alternative the agent would use instead. It does not explicitly state when-not to use it, but the destructive framing plus the revert pointer covers most selection needs.

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 readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so safety is largely covered. The description adds one genuinely useful side-effect clarification ('Nothing scheduled is affected'), but says nothing about reversibility (can it be re-added?) or whether repeating the call is harmless despite idempotentHint=false.

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, effect stated first and the side-effect caveat second. No padding or repetition; 'Drop' is slightly informal relative to the tool name but no information 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 simple two-parameter mutation, the description covers the what and one side effect, and annotations carry the safety profile. However, with no output schema and a 50%-documented schema, the origin of suggestionId and reversibility remain unexplained.

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 50%: 'site' is documented in the schema while 'suggestionId' is bare (minLength only). The description does not compensate by saying where suggestion IDs come from (e.g., get_plan) or what an invalid ID does, so the undocumented parameter stays opaque.

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 ('Drop') and resource ('one of the plan's suggestions') with a stated outcome ('stops being offered'). An agent can infer this is the inverse of accept_plan_suggestion, though the sibling is not named explicitly.

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 outcome clause implies the use case (removing an unwanted suggestion), but there is no explicit when-to-use guidance and no differentiation from near-name siblings like dismiss_topic, dismiss_update, or remove_plan_entry. The agent must infer the boundary from 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 readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is already carried by structured data. The description adds genuinely new behavioral context beyond that: the hide is presentation-only and the planner may still use the topic, plus the undo semantics. It does not mention permissions or persistence across sessions, so it stops short of a 5.

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

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

Three tight sentences: effect and scope first, reversal second, disambiguation from the sibling last. No restatement of the title, no filler, and the most decision-relevant constraint 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?

With no output schema and only three parameters, the description covers what an agent needs: what is hidden, that the effect is presentation-only, how to reverse it, and which sibling to pick instead. Minor gaps remain around authorization requirements and whether the dismissal persists, but nothing blocking 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 67%: 'site' and 'label' are documented in the schema, but 'undo' has no schema description. The description compensates for exactly that gap by defining undo ('shows it again'), which is the one parameter the schema leaves bare. Remaining param details add nothing further, so 4 rather than 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 ('Hide') and resource ('a research topic card from the plan's topic views') and immediately bounds the effect with '(presentation only: the planner may still use it)'. It also names the sibling it is not — exclude_topic — 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?

Explicitly gives the alternative and the condition that selects it: 'To stop the planner from ever scheduling it, use exclude_topic instead.' It also documents the reversal path ('undo: true shows it again'), covering both directions of use.

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, destructiveHint=false, and idempotentHint=false, so the mutation/safety profile is partly covered. The description adds the useful disclosure that 'the page is untouched', clarifying the write is confined to the proposal state, but it omits what happens to the update record itself and that repeat calls are not idempotent.

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, front-loaded sentences with zero filler. The action and its key consequence are stated immediately.

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 mutation tool with no output schema, the description covers the page-safety consequence but not the update's resulting state, permissions, or failure/repeat-call behavior, and it leaves one of two parameters entirely undocumented. Adequate but with clear 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 50%: 'site' is documented (though with a single hard-coded value) while 'updateId' has no description anywhere. The description provides no parameter meaning at all, so it fails to compensate for the coverage gap.

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

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

States a specific verb (close/dismiss) and resource (proposal or draft), and distinguishes the outcome from publishing, which separates it from approve_update and publish_draft. It does not explicitly name those siblings, so it falls short of full differentiation.

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

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

The phrase 'without publishing it' implies the contrast with approve_update/publish_draft, but there is no explicit when-to-use guidance or statement of what condition selects dismissal over approval. Usage is left to inference.

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

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

Adds substantial context beyond the annotations: it is slow (several LLM calls, 1-3 minutes), synchronous, returns a concrete payload (new title, meta description, full HTML, before/after), and publishes nothing. It also discloses failure and refusal behavior — safety-check failure reverts the row to "proposed" with a reason, and a hand-edited draft causes refusal because it would be overwritten — none of which appears in the structured fields.

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

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

Front-loaded with purpose and scoping, then cost, then return value, then routing — a sensible order with no filler. It is a dense single paragraph with many parenthetical clauses, which costs a little readability but every sentence carries 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?

No output schema exists, and the description compensates by enumerating the return payload. Combined with the latency warning, the non-publishing guarantee, and the failure/refusal paths, an agent has everything needed to call this correctly and set expectations.

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%; the description never mentions updateId directly, though it does implicitly characterize it by explaining that "retarget", "sections" and "full" rows behave differently, which helps an agent understand what kind of update it is targeting. The site enum is only documented in the schema, so the description adds partial but not decisive semantic value.

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

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

Opens with a specific verb+resource ('Write the improved version of a proposed page update') and immediately scopes it to rows in status "proposed". It distinguishes itself from the neighboring draft tools by explaining that it produces the content, while edit_update_draft, approve_update and dismiss_update act on it afterward.

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

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

Explicitly names the downstream alternatives ('Next: edit_update_draft to tweak it, approve_update to publish, or dismiss_update') and states a blocking precondition (refused when a hand-edited draft exists). It doesn't spell out the inverse case — when to prefer edit_update_draft over re-running this — so it stops short of a full when/when-not matrix.

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-destructive, non-idempotent, closed-world write, so the safety burden is partly lifted. The description adds that the new entry is grouped with the original, which is useful behavioral context beyond the annotations. It says nothing about permissions, limits, what fields the copy inherits, or how the caller obtains the new entry's identifier.

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 of roughly equal weight, both earning their place: the first defines the operation and its purpose, the second routes the agent to the correct follow-up tool. Nothing is padded and the key fact 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 simple two-parameter write, the description covers purpose, outcome and follow-up. However there is no output schema, and the description never says what the call returns — notably the new photo's identifier, which the caller needs before the recommended update_photo step. That gap is the one thing a fully complete definition would close.

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 50%: 'site' is documented in the schema but 'photoId' has no description anywhere. The description text mentions no parameters at all, so it does not compensate for the gap — an agent gets no help identifying which photo is being duplicated or what constraints apply.

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 and resource ('Copies a bank entry') plus the business rationale ('a second colour, size or stage of the same product'), and explicitly names update_photo as the tool that handles subsequent edits, which separates it from the sibling it is most easily confused with. The only friction is that it calls the resource a 'bank entry' while the tool name and siblings talk about 'photo', forcing a small inference.

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 'when' is stated concretely: use it when a second colour, size or stage of the same product is needed, so the copy stays grouped with the original. It also names the follow-up step ('Edit the copy with update_photo afterwards'), which is genuine sequencing guidance. There is no explicit 'do not use this for...' exclusion, 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 mark this as non-read-only, non-destructive, non-idempotent. The description adds real behavioral content beyond that: the status='ready' gate, partial-update semantics ('Fields you omit are kept'), and a content validity constraint ('keep at least a few paragraphs'). It does not say what happens to a draft that is not ready or whether edits can be reverted.

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

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

Three short sentences, zero filler, with the action and target front-loaded and the precondition and partial-update rule following. Every clause earns its place.

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

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

For a no-output-schema mutation tool with 5 params, the description covers the operation, the precondition, the editable field set, and the omit-keeps-existing rule. Missing only updateId guidance and an explicit alternative for the non-'ready' case, which is minor.

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 'site' is documented), so the description must carry the load and largely does: it explains that title, metaDescription and contentHtml are the editable fields and imposes a length expectation on contentHtml. updateId and the 200/300 char limits are left to the schema, but the semantics of the mutation surface are well covered.

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 (edit/change) and resource (update draft) and enumerates the mutable fields: title, metaDescription, contentHtml. The phrase 'before approving it' implicitly separates it from approve_update, though it never names that sibling 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?

Gives a concrete precondition ('Only drafts in status "ready" can be edited') and a temporal context ('before approving it'). It stops short of explicitly naming approve_update, publish_draft, or revert_update as alternatives, so routing is implied 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 only declare the safety profile (readOnly=false, destructive=false, idempotent=false). The description adds real behavioral context beyond them: the exclusion is persistent into all future planning, add_to_plan will refuse the item, already scheduled or published articles are unaffected, and the call is free. That is exactly the downstream-effect disclosure a mutation tool 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?

One dense paragraph, front-loaded with the effect, then the input rule, the undo path, and the cost. No filler sentences and no restatement 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?

Three simple parameters, no output schema needed, and the description covers effect, scope of impact, input constraint, reversal, and cost. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a constraint the schema cannot express: the mutual exclusivity of keyword and topic, plus the definition of topic as a cluster label from get_keywords. This meaningfully reduces misuse.

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 ('Hard-excludes one keyword or one topic label from all future planning') and clarifies the dual-mode input. It does not differentiate itself from the sibling exclude_topic, which appears to cover the topic half of this tool's surface, so an agent still has to guess which of the two to call for a topic label.

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 usage constraint ('Give exactly one of keyword or topic') and names the reversal path ('Undo with restore_keyword'). It stops short of explicit when-to-use guidance relative to the sibling exclude_topic/dismiss_topic tools.

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

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

Annotations mark this as a non-read-only, non-destructive write, and the description adds genuinely useful context beyond them: the change is forward-looking only, pre-existing scheduled entries are untouched, and undo:true reverses it. The reversibility detail matters because idempotentHint=false could otherwise read as irreversible. It does not contradict any annotation.

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

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

Three short sentences, front-loaded with the core action, then the scope constraint, the escape hatch, and the parameter rule. No filler and nothing repeated from the schema.

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

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

With no output schema and half the parameters undocumented structurally, the description carries the important behavioral load well — effect scope, reversal, and the exclusive-or parameter rule. Minor gap: it does not say what happens if neither or both of topic/keyword are supplied beyond the stated constraint.

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 50% (site and topic documented, keyword and undo bare), so the description must compensate — and it does: it clarifies that keyword is the single-keyword alternative to topic, that undo:true restores the exclusion, and that exactly one of topic/keyword may be supplied. Site semantics are left to 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?

Specific verb ('exclude'/'tell the planner never to schedule') plus the two resource types it accepts (topic, keyword), with the exclusivity rule stated. It is clearly distinguishable from siblings like exclude_keyword, dismiss_topic, and remove_plan_entry.

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 states the effect scope ('only affects future generation') and names the alternative for already-scheduled entries: remove_plan_entry. It also gives the undo path. What it does not do is explain when to prefer this over its sibling exclude_keyword, leaving the topic-vs-keyword sibling routing implied 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?

With annotations present, the description still adds real operational context the annotations don't carry: latency ('page fetch plus a vision call'), a per-site daily cap with the 429 BRAND_COLORS_CAP code, and the fact that it overwrites prior colours. The overwrite behaviour sits in mild tension with destructiveHint=false, but the description is explicit enough that the agent is not misled.

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 output, then constraints, then the alternative. It is information-dense and runs long as a single stream, but every clause (output roles, side effect, cap, follow-up tool) 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?

There is no output schema, and the description compensates by specifying the return shape ({role, hex} for five roles). It also covers the failure mode (429 cap), the side effect (replacing prior colours), and the follow-up path, leaving nothing an agent needs 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?

Only one parameter (site), and schema description coverage is 100%, so the schema already fully documents it. The description adds nothing about the site argument itself, so the baseline 3 applies.

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

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

States a specific verb and resource chain: 'Fetches the site's homepage, derives five swatches... and SAVES them as the site's image-style brand colours.' It names the exact output (primary, secondary, accent, background, text), so an agent knows precisely what this produces and can distinguish it from generate_* or update_settings 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?

Anchors usage to a concrete UI equivalent ('the same as the Images tab's "Read from my site" button') and routes follow-up edits to update_settings imageStyle.colors. It implies when not to rely on it repeatedly (slow, daily cap), but never states explicit when-to-use-vs-alternative 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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description only needs to add incremental behavior. It does add two useful traits: the result is 'paginated' and the optional sitemapUrl is restricted to the site's domain or subdomain. It does not disclose default page size or ordering, keeping it short of a 5.

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

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

Two sentences, front-loaded with the core verb and resource, then the behavioral facts. The parenthetical about domain/subdomain is dense but informative rather than wasteful; nothing extraneous, though it could be tightened.

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 burden of describing what comes back, and it does state the return content (page URLs) plus pagination. It does not describe the response shape, item ordering, or what an empty/absent sitemap yields, so it is strong but not fully 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 50%: 'site' and 'sitemapUrl' are documented in the schema, while 'limit' and 'offset' are bare. The description's 'paginated' hints at those two parameters but adds no bounds or semantics (e.g., max 100, default page size) beyond what the schema already states for the covered half. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Lists the page URLs in the site's sitemap') and adds the scope constraint that the sitemap URL must live on the site's own domain or a subdomain. The link to 'update_settings internalLinks' tells the agent exactly what this data feeds into, which no sibling tool duplicates.

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?

Frames the use case clearly by calling the output 'the raw material for update_settings internalLinks', implying when an agent should reach for it. However, it names no explicit alternative and states no when-not conditions, so it falls short of full 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 only declare the generic safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description goes well beyond them: it discloses that an account snapshot (plan, platform, cadence, recent failures) is attached automatically, that replies arrive by email at the account address, that it works on a frozen site, and that throughput is capped at a few per hour.

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?

Roughly five short sentences, front-loaded with the action and payload before moving to prerequisites and rate limits. Every clause carries information, though the enumerated field list in the opening sentence partially duplicates the schema.

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

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

With no output schema, the description closes the loop by explaining how the outcome is delivered (email reply to the account address) and what context the team receives automatically. For a 4-parameter submission tool this covers everything an agent needs 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 description coverage is 100%, so all four parameters (site, subject, message, category) are already documented with length bounds and enum values. The description restates the parameter set and adds light guidance on what the message should contain, but contributes little syntax or format detail the schema does not already carry, so the baseline 3 applies.

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

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

States a specific verb and resource ('Files a support request with the Blawgy team about this site') and enumerates the payload (subject, message, optional category). The scope is narrow enough to distinguish it from the many other sibling tools, and the mention of the account snapshot clarifies what the tool actually transmits.

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 triggers ('when something is broken, when the help docs (search_help) cannot answer, or when the customer asks to talk to a person') and names the alternative sibling (search_help) with the condition that selects it. It also notes the frozen-site case, which is a meaningful branch condition.

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 behavioral context the annotations cannot convey: a latency warning ('Slow (LLM plus web)'), deduplication against already-saved competitors, and the crucial point that 'Nothing is saved' plus where to persist results. This is the non-obvious operational information an agent needs; only the return shape is left unstated.

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 input source, dedup behavior, and cost warning in two tight fragments; every clause carries distinct information and the routing hint is last. 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 suggestion-generating tool with no output schema and a mutation-ambiguous annotation set, the description covers inputs, side effects (none), and follow-up. The one gap is that it never hints at the shape of the returned suggestions, which an agent must guess.

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' is documented but 'productDescription' has no schema description. The description compensates by explaining that a supplied description overrides the saved one, giving the parameter meaning beyond its name, though it never states the format/length expectations.

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 (researches/suggests), a specific resource (competitor domains for this business) and a scope qualifier (skipping competitors already saved). This clearly separates it from siblings like get_keyword_recommendations or add_my_keywords without needing to open any schema.

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

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

Gives the input-selection rule ('using the saved description unless one is given') and, importantly, tells the agent what to do next: 'pass the ones to keep to update_settings competitors.' It lacks an explicit when-not-to-use statement or a warning not to expect this tool to persist, but the save-path routing effectively covers that.

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 annotations: 'Slow' discloses latency, and 'Nothing is saved' reconciles the readOnlyHint=false annotation with the fact that no state is persisted, which prevents an agent from assuming it mutates settings. It does not mention auth or error behavior, but the key behavioral facts for a generator are covered.

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, each earning its place: what it does, how slow it is, and what to do with the output. The critical no-persistence warning is front-loaded before the follow-up 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?

There is no output schema, and the description explicitly handles the return value by telling the agent to feed it to update_settings. For a single-parameter generative tool, the combination of purpose, latency, persistence semantics, and follow-up action is 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 the schema already documents the single 'site' parameter fully. The description's 'Reads the site' only implicitly ties back to that parameter and adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

Specific verb + resource: 'Reads the site and writes a business description.' It distinguishes itself from lookalike siblings (generate_titles, generate_outline, analyze_new_site) by naming the output artifact, a business description, and the fact that it is only a starting draft.

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 forward guidance: use the result by passing it to update_settings businessDescription. It explains the context of use (a starting point) but does not state when-not to use it or which sibling to pick for adjacent text-generation tasks, so it stops short of explicit alternatives.

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

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

Annotations cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=false) but not cost or lifecycle. The description adds real context: output is saved as DRAFTS for owner review, execution is slow (minutes for a big batch), and it waits and returns per-target results. It does not spell out duplicate-creation risk on re-run despite idempotentHint=false, which is the one notable gap.

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

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

Three sentences with no waste: the core action first, then the behavioral cost/lifecycle note, then the alternative routing. Front-loaded and every sentence earns its place.

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

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

With no output schema, the description usefully notes it returns per-target results, which is the key return-shape information. For an 11-param batch mutation tool it could still say more about partial failures or permissions, but the draft lifecycle, latency and alternative 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 description coverage is 55% with 11 parameters, so the schema carries much of the load. The description adds meaning for targets (the town/product/event each page is rewritten for) and implies templatePageId is the cloned source, but leaves slugPattern, titlePattern, stripPhrases, generateFeaturedImage and baseKeyword unexplained. Marginal value beyond the schema, so 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 precise verb and resource chain: clones the template page once per target, rewrites each for its town/product/event, and saves them as drafts. It explicitly distinguishes itself from publish_location_pages, so an agent can tell the two apart 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 an explicit routing rule: use this for drafts, use publish_location_pages to publish live instead. The condition that selects the alternative is stated rather than left to inference. The only minor omission is that sibling preview_location_pages is not named, but the primary decision branch is fully 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 only declare it is not read-only, not idempotent and not destructive; the description adds real context beyond that — it is a single LLM call, it draws on the site's business profile, audience and guardrails, and it emits a section outline. It stops short of stating cost, latency or failure/retry behavior for the LLM call.

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

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

Three short sentences, front-loaded with the pipeline position, then inputs/output, then the next-step routing. No filler and no repetition of schema fields.

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 sketching the return structure and confirming the pipeline hand-off values. With 90% schema coverage on the 10 parameters and annotations covering the safety profile, an agent has everything needed to call this correctly.

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

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

Schema coverage is 90%, so the baseline is 3, but the description adds workflow meaning the schema cannot: `title` is the one chosen from generate_titles and `prompt` is the original brief from that step, which tells the agent where these values must come from. It says nothing extra about the remaining options (urls, articleType, link/video flags), leaving that to 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?

Specific verb (turn ... into) and resource (section outline), with the exact input pair (chosen title + original prompt) named. The output shape `{ sections: [{ id, title, ... }] }` further pins down what is produced, and the step-2 framing separates it from generate_titles and write_from_outline.

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 positions the tool as step 2 of the Builder and names both follow-on routes (write_from_outline with title+outline, or regenerate_outline with feedback). It gives clear context but does not state exclusions, e.g. when to prefer remix_from_urls or write_article_now instead of entering this pipeline.

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 give the safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds substantial context beyond them: re-call safety with existing entries preserved, autonomous self-writing at the site's cadence, and the 'held' behavior returning status 'queued' with kind 'research'. This is exactly the behavioral detail an agent needs and cannot get from the structured fields.

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

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

Front-loaded with the primary action, then the idempotency note, then the async/held branch, then the alternative tool. Sentences are dense but each earns its place. Slightly long, but no wasted 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, and the description compensates by specifying the return shape ('status "queued"' with 'kind "research"') and the side effects (scheduled entries write themselves). It also names the sibling it is not. 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 description coverage is 100% (both site and horizonWeeks are documented with enum values), so the schema carries the parameter burden. The description mentions the 'planning horizon' which loosely maps to horizonWeeks but adds no syntax or constraint 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?

The description opens with a specific verb+resource ('Generate the content plan, or refill the open slots in the planning horizon from the site's keyword research'), clearly distinguishing this from siblings like get_plan, add_to_plan, and update_plan_entry. An agent can identify the operation without inspecting 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 explicitly routes the agent to an alternative ('Use add_to_plan to add one specific keyword instead') and describes the exact recovery flow when research is still running (poll with get_job, then call generate_plan again). When-to-use and what-to-do-instead 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 declare this is a non-read-only, non-destructive, non-idempotent call; the description adds the important cost context that it consumes 'One LLM call against the user's builder budget,' which a caller cannot infer from the annotations. It does not discuss latency, retries, or what happens on repeated calls, so it stops short of a 5.

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

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

Four tight sentences, front-loaded with the step identity and the core input/output, then sequencing, then the alternate path. No filler and nothing repeated from the schema.

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

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

For a 10-parameter, no-output-schema tool it covers the flow, cost, and routing well; return value is only gestured at ('title options back'), and parameters like temperature, useExternalLinks, and useYouTubeVideos rely entirely on the schema. Adequate, though the output shape could be a phrase richer.

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 real meaning: it defines what `prompt` should contain (topic, audience, angle) and demonstrates the `articleType` 'remix' case paired with `urls`. This goes beyond the schema strings for the two most decision-relevant parameters.

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 ('get title options back') within a named flow ('Article Builder, step 1'), and distinguishes the tool from siblings by naming generate_outline as the next step and remix_from_urls as the batch alternative. An agent can place it precisely in the builder pipeline without opening the schema.

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

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

Explicit about when to call it (start of the builder, given a prompt), what to do next (pick a title and call generate_outline with the same prompt/options), and the alternates for a different case (articleType 'remix' with url, or remix_from_urls for all steps). Both the sequencing and the branching condition are stated, not implied.

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

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

Goes well beyond the readOnly/idempotent annotations by disclosing Pro+ gating, the cost model (free read vs credit-spending scan), and the freshness contract: snapshot is null and stale=true until one exists or is older than a day. This is exactly the behavioral context an agent needs to interpret the response.

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 constraints and routing. Dense and information-rich with no filler sentences, though the parenthetical definition of `stale` and the semicolon-chained clauses make it slightly cramped rather than crisp.

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 by enumerating the result fields (query, answer snippet, source URL, competitor landscape). Combined with the Pro+ gate, snapshot freshness rules, and the scan/poll alternative, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so all four parameters are already documented in the schema itself. The description reinforces includeHistory (trend over past scans) and the model filter, but adds no syntax or format detail beyond what the schema provides. Baseline 3 applies 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?

States a specific verb and resource (returns AI citation/mention data for a site) with the full granularity of what's covered: totals, citation rate, by-model breakdown, citing sources, competitor landscape, individual mentions. It also implicitly distinguishes itself from run_ai_mentions_scan by naming that sibling for fresh scans.

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 (read the stored snapshot, free, Pro+ only), when not to expect fresh data ('nothing is scanned by this tool'), and routes to the alternative workflow ('Run a fresh scan with run_ai_mentions_scan, then poll get_job kind=ai_scan'). Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower. The description adds genuinely new behavioral context: includeText returns the full plain-text body, and unwritten scheduled entries return no body. It omits any note on size, pagination or error behavior, but the added disclosure is real.

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 a compact inventory of returned fields and two short caveat sentences. The field list is long but each item earns its place given there is no output schema; no filler sentences.

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, plus notes the empty-body case for scheduled articles. Minor gap: no guidance on choosing between sibling read tools or on includeHtml's default, both of which the schema partly covers.

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 baseline is 3. The description restates includeText semantics that the schema already documents and does not add format or constraint detail for site/id 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?

Starts with a specific verb+resource ("Read one article in full") and then enumerates exactly what is returned (title, slug, meta description, URLs, HTML body, excerpt). This clearly distinguishes it from list_articles (many) and get_article_preview_url (URL only) without needing 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?

Usage is implied by "Read one article in full" and it does tell the agent to pass includeText for plain text and that scheduled entries have no body. However, it never explicitly routes the agent between this tool, list_articles, get_article_preview_url and update_article, so no when-not guidance exists.

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, closed-world), so the bar is lower, yet the description still adds real behavior: it works on unpublished/draft/held articles and it validates that the article exists first, hinting at a failure mode. It omits whether the link expires or requires authentication to open.

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 no filler, front-loading what the tool returns before adding the scope and validation caveat. Every clause earns its place.

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

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

For a simple read-only tool with no output schema, the description explains the return value well (a link a human can open) and notes the existence check. Minor gaps remain around permissions and link lifetime, but nothing critical is missing for correct invocation.

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

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

Schema description coverage is only 50%: 'site' is documented in the schema, but 'id' carries no description anywhere. The description only refers obliquely to 'the article', so it does not compensate for the undocumented identifier parameter (format, accepted values, or lookup behavior).

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+resource (get a preview link for an article) and clarifies the return value is a human-openable URL rendered as Blawgy would render it, which separates it from get_article-style content retrieval. It does not name a sibling tool explicitly, so differentiation is implied 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?

It gives clear context for when this is the right tool: when you need a link a person can open, including for unpublished, draft and held articles that other endpoints would not expose. It stops short of naming alternatives (e.g. get_article) or stating when not to use it.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is the 28-day data window, the pixel dependency, and the Pro+ entitlement requirement -- real access/auth context. With no output schema, it also carries the return-shape burden and discharges it well, enumerating median active seconds, scroll depth, exit section, and per-section funnel. It does not mention rate limits, empty-state behavior, or what happens when the pixel is off.

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 time window, then the no-path case, then the with-path case, then the entitlement caveat -- a logical build with no filler sentences. Each clause carries distinct information an agent needs before invoking.

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

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

For a read-only reporting tool with no output schema, the description covers the data window, entitlement gate, and both result shapes, which is nearly everything needed. Two small gaps: the trailing 'Free.' fragment is ambiguous about plan eligibility, and nothing addresses the limit parameter's effect on the top-pages result size.

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 all three parameters are already documented, including the path/omit semantics that the description largely restates. The description contextualizes what the path parameter unlocks (funnel, click and referrer breakdowns), which is marginally useful, but it never mentions the limit parameter or its default/max, 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 and data source: 'Reader engagement from the Blawgy pixel over the last 28 days,' and unambiguously splits the two modes (top-pages summary vs. single-page profile) with their distinct payloads. An agent can tell what this returns without opening the schema, though it never names or contrasts a sibling such as get_traffic or get_overview, which would fully settle the choice.

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 precondition for use -- 'Pro+ (pixel must be on in Settings)' -- and tells the agent which invocation shape to pick based on whether it has a path. It stops short of stating when NOT to reach for this tool or which alternative to prefer for general traffic metrics, so routing vs. siblings remains implicit.

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/destructiveHint=false, so the safety profile is covered; the description's 'Read only' is largely redundant. However, it adds genuinely new behavioral context beyond annotations: the white-label visibility rule and the fact that plan changes must be routed to get_upgrade_link rather than performed here. It stops short of mentioning auth/permission needs or what happens when no subscription exists.

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

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

Two tight sentences, front-loaded with the substantive content (what data is returned) before the caveats and the alternative tool. No filler or restatement 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?

With no output schema, the description carries the return-value burden and does so by enumerating the fields delivered. Combined with the visibility caveat and the pointer to the mutation tool, an agent has everything needed to call this correctly and interpret its scope.

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

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

There is a single required parameter ('site') and schema description coverage is 100%, with the schema already listing the valid site value. The description mentions 'The site's subscription' but adds no format or selection guidance beyond the schema. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

The description names the exact resource (the site's subscription) and enumerates the concrete fields returned — plan, status, trial, renewal date, cancel-at-period-end, failed-payment freeze — plus the available upgrade plans. It also separates itself from the sibling get_upgrade_link by naming it as the tool for changing plans. An agent can tell what this returns without opening the schema.

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

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

It gives an explicit alternative and its trigger ('Use get_upgrade_link to change plans in the browser'), which tells the agent what this tool does NOT do. It also states a when-not condition: the tool is hidden for white-label customers whose partner bills them, so an agent knows results may be absent for those accounts.

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 safety (readOnly, idempotent, non-destructive). The description adds real behavioral value beyond them: the defaults ('trailing 28 days'), the auth precondition ('Needs Search Console connected'), the cost ('Free'), and what is returned (clicks, impressions, top queries).

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

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

Purpose is front-loaded, followed by interpretive context, defaults, and preconditions in a compact block. Every sentence carries information, though the trailing 'Free' fragment is slightly abrupt in structure.

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 steps in to describe the return contents (clicks, impressions, top queries per side) and the default range. Combined with the schema-covered parameters and annotations, an agent has nearly everything needed, with only alternative-tool routing left implicit.

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

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

Schema coverage is 100%, so all four parameters are already documented. The description reinforces the date-range semantics and default window but adds no syntax or format detail the schema lacks, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('Splits Google Search Console queries into branded... and non-branded'), defines branded parenthetically, and names the metric content on each side. An agent can distinguish it from get_traffic, get_seo_snapshot or get_rankings 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 implies when the tool matters ('Non-branded growth is the clearest sign Blawgy content is working') and gives preconditions (GSC connected, free). However it never names an alternative sibling (e.g., get_traffic, get_overview) or an explicit when-not to use it, so routing still requires 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, destructiveHint=false and openWorldHint=false, so safety is covered and the bar is lower. The description adds real value by disclosing the payload shape (HTML article body, selected title, featured image), which substitutes for the absent output schema. It stops short of covering auth, site scoping, or not-found behavior.

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

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

Two sentences, no filler, and the payload enumeration is front-loaded right after the verb. The second sentence immediately converts the payload into actionable next steps.

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 enumerated field list is exactly what an agent needs to know what comes back, and annotations cover the read-only profile. Minor gaps remain: no guidance on failure when draftId is invalid, and no mention of the site-scoping requirement beyond the required schema parameter.

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%: only 'site' is documented in the schema, and draftId has no description. The description implicitly characterizes draftId as a builder-draft identifier by saying it can be handed to publish_article_from_builder, which is modest added meaning, but it says nothing about the site parameter or ID format.

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

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

States a specific verb and resource with scope: 'Read one Article Builder draft in full,' then enumerates exactly what 'full' contains (brief, titles, selected title, outline, written article with HTML, keywords, featured image). This clearly separates it from list_builder_drafts and delete_builder_draft in the sibling set.

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

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

Gives explicit downstream routing: use the returned pieces as arguments to the step tools, or pass the draftId to publish_article_from_builder. That is clear context for why an agent would call this. It does not, however, state how to obtain a draftId (e.g., list_builder_drafts) or what to do if the draft does not exist.

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 flag it as non-read-only, non-idempotent, non-destructive, but the description adds real behavioral context the annotations lack: the link expires in a few minutes and must be opened by a HUMAN in a browser. It doesn't mention permission requirements or what happens on repeated calls, so it falls short of a 5.

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

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

Four short sentences, front-loaded with the core action, followed by the expiry behavior and then the sibling disambiguation. Every sentence carries information the agent needs.

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 correctly states what is returned (the OAuth URL) and adds the expiry and human-in-the-loop constraint. It is nearly complete for a two-parameter link-generation tool, missing only auth/permission expectations.

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' is described in the schema while 'provider' only carries an enum of 'gsc'. The description says 'for this site' but adds no meaning beyond the schema for either parameter, so the baseline of 3 for partial coverage is appropriate.

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

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

States a specific verb and resource: returns the OAuth URL to connect Google Search Console. It also names the sibling tools for the other providers, so an agent can distinguish this from connect_bing and connect_platform 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?

Explicitly states when to use it (human opens the GSC OAuth link in a browser) and routes the alternatives: Bing uses connect_bing with an API key, and Shopify has no OAuth link, using connect_platform instead. Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description still adds genuine value by disclosing the security-relevant behavior that API keys are never returned, only hasKey, plus the return contents. "Read only" merely restates readOnlyHint, which is why this isn't 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 dense, front-loaded sentence with no filler; the trailing "Read only" is the only mildly redundant phrase given the readOnlyHint annotation.

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 burden of describing return content, and it does so completely: connection state, locations, hasKey instead of keys, sync timestamps, and recent errors. An agent knows what it will get and that it is a safe read.

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 (site) with 100% schema coverage and an enumerated value, so the schema already carries full meaning. The description adds nothing about the site 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?

The description names the resource (Dutchie connection status) and enumerates exactly what is returned: connection state, connected locations, last/next sync, and recent sync errors. That content scope implicitly separates it from siblings like connect_dutchie, sync_dutchie, and remove_dutchie_location, though it never names an alternative explicitly.

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?

"For dispensaries" scopes the audience, and a status tool's usage is reasonably inferable (checking connection health before syncing), but there is no explicit when-to-use guidance or routing against connect_dutchie/sync_dutchie.

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

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

The annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so "Read only" is a restatement of structured data rather than added value. The one genuine behavioral detail is the daily scoping implied by "left today" (a quota that resets), but nothing is said about what happens at zero remaining or any rate 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?

Two short sentences, front-loaded with the return content, then the routing hint. The first sentence is slightly convoluted ("the next few scheduled article titles a preview can be rendered on") and "Read only" is redundant with the annotations, costing a point.

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 correctly carries the burden of explaining the return value, and it does so (count plus sample titles). Only the zero-quota / failure behavior is left unstated for a read-only check the agent is told to call unconditionally before another 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% and the single `site` parameter is fully documented in the schema, including its allowed value. The description's "for this site" merely echoes that, adding no format or constraint detail. 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 precisely what the tool returns: the remaining daily preview allowance plus the next few scheduled article titles eligible for a preview. That is far more specific than the tool name alone and separates this from the broader get_* listing tools (list_articles, get_overview) an agent might otherwise reach for.

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 before preview_image_style" gives an explicit sequencing rule that answers the main when-to-use question. There is no when-not guidance or error-case exclusion (e.g. what to do if the allowance is zero), 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 readOnlyHint, idempotentHint, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new context beyond that: the weekly refresh cadence (staleness) and the 'Free' cost signal. However it doesn't describe output shape or size, so it stays at solid-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?

One dense, front-loaded sentence listing coverage areas, followed by a short sentence pairing the refresh cadence with the alternative and cost. No filler, though the first sentence runs long as a list.

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 categories so an agent knows what to expect. It is largely complete for a simple read tool, leaving only the exact response structure unspecified.

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

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

Single parameter with 100% schema description coverage, including the explicit allowed value, so the schema carries the semantics. The description adds nothing about the parameter, which matches the baseline of 3 when the schema is fully documented.

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 exactly what the tool returns — sitemap found, whether it lists published posts, GSC errors, Bing submissions, and a fix list — which is specific and distinguishable from the sibling recheck_indexing. It reads as a noun phrase without an explicit verb, but the resource and scope are unambiguous.

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 states the data is refreshed weekly and explicitly routes to recheck_indexing for an immediate refresh, giving a clear when-to-use-this vs. that distinction. It does not cover exclusions or prerequisites, but the alternative is named with its triggering condition.

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, and closed-world, so the safety profile is covered. The description adds genuinely non-structured context: the normalized return states, the existence of a kind-specific detail block, polling cadence, and cost ('Free'). It could say more about behavior on a wrong/missing id, which is why it isn't 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?

Front-loaded with the core purpose and return normalization before the denser kind-to-id mapping, and the operational notes (cadence, cost) are compact. It is information-dense and readable, though the long parenthetical kind list makes the middle section heavy; still, every clause carries 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 correctly carries the return-value burden by naming the normalized statuses and the kind-specific detail block, plus cadence and cost. For a 3-parameter polling tool this covers everything an agent needs to call it correctly and interpret the result.

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

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

Schema description coverage is 100% and the enum is already documented, so the baseline would be 3. The description exceeds that by disambiguating the generic 'id' parameter per kind – telling the agent exactly which kinds need no id and what the id means for article, update_draft, post_image, and plan_topic_add. That is real semantic value beyond the schema's generic 'job key' text.

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

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

States a precise verb+resource ('Status of background work started by another tool') and goes further by naming the exact normalized state vocabulary (queued | running | complete | failed | unknown). This is unambiguous and distinguishable from sibling read tools like get_research_status or get_product_sync_status, since it positions itself as the generic poller for all async kinds.

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 guidance: poll every 15-30 seconds, most jobs finish within a few minutes, and it maps each kind back to the tool that started it (write_article_now, add_to_plan), which tells the agent when this tool is the right follow-up. It stops short of explicitly naming when NOT to use it versus overlapping siblings, so it doesn't reach a 5.

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