seodraft

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

Less explicit than annotations alone: it explains the lifecycle and side effects that annotations don't cover. It details saidByHuman semantics (true only for transcription; inferred/measured/fetched false and waits for approval), storage outcomes (true becomes accepted with source 'conversation'; false becomes pending and blocks brief.evidence until accepted), weakFirsthand semantics (never blocks), deduplication on text (never resets a human verdict, duplicates named in response), and pendingReview meaning. This adds rich behavioral context beyond the provided hints such as idempotentHint, destructiveHint, readOnlyHint, openWorldHint.

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

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

The description is dense and front-loaded with the core purpose, but it is a long run-on paragraph mixing multiple concerns (purpose, saidByHuman logic, storage outcomes, weakFirsthand, deduplication, pendingReview) without clear structure. It is not unduly verbose for the complexity, but readability and scanability could be improved with paragraph breaks or bullets. Every sentence does carry distinct information.

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

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

For a 2-parameter mutation tool with no output schema and 50% schema coverage, the description is quite complete: it covers purpose, approval workflow, deduplication behavior, and response fields. It leaves some gaps around the kind enum and source parameter semantics, and doesn't explicitly say the tool is non-destructive/openWorld, but annotations cover safety and the description covers the nuanced business logic that annotations cannot.

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%, so half the parameters (items and its nested fields) are only enumerated as a shape in the schema, not explained in the description. The description explains the semantics of saidByHuman, weakFirsthand (though not in the schema at the top level), source 'conversation', and deduplication on text, adding value. But it does not fully compensate for the coverage gap, nor explain kind enum or source field meaning. 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 states a specific verb (add) and resource (evidence bank) and immediately qualifies the scope with a parenthetical definition: 'what only this business knows' followed by concrete examples (a measured number, a named case, a mistake made, a credential, a screenshot to take). This distinguishes it from siblings like add_topics or list_evidence, and an agent can tell what belongs in this tool without opening the schema.

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

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

The description gives clear context: it is the source pool that articles draw from ('Every article draws at least three accepted pieces from it'), implying when to add. However, it does not explicitly contrast with siblings like add_topics or list_evidence, or state when not to use this tool. Usage is strongly implied but not fully routed against 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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), it discloses cost (~USD 0.11 per batch), 30-day skip behavior, spend-limit refusal via degraded:true with nothing charged, and per-outcome semantics for duplicates, similar, published, semanticOverlaps, unmeasured and resurrected. This is unusually rich disclosure for a mutating 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?

For a tool with no output schema, the dense prose is doing necessary work: cost and skip rules are front-loaded, then return-field semantics. Some sentences are telegraphic ('duplicates names terms identical to something already there'), but almost every clause carries actionable information rather than restating structured 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?

With no output schema and 25% schema coverage, the description carries the return-value and behavior burden and mostly does so: it enumerates the result buckets (measured, unmeasured, duplicates, similar, published, semanticOverlaps, resurrected) and status values. Gaps remain around the `source` parameter and the exact shape of the `terms` input.

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

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

Schema description coverage is only 25%, so the description must compensate. It explains allowSimilar well (re-sending stores withheld terms, inserted:true), but never clarifies the `terms` payload or the `source` enum (add/generate/chat), leaving half the parameters under-specified. Partial compensation merits a 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?

The opening sentence states a specific verb and resource ('Adds questions to the topic bank'), and the surrounding detail about measurement, cost, and dedup makes clear this is the write path distinct from siblings like plan_topics, propose_topics, suggest_topics, and research_topic. An agent can identify the tool without opening the schema.

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

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

The description thoroughly explains what happens during a call (cost, dedup checks, allowSimilar overrides) but never states when to choose this tool over the adjacent topic tools (propose_topics, suggest_topics, plan_topics). Usage is implied by the topic-bank framing 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?

Goes well beyond the annotations by disclosing the gate-refusal behavior and its degraded reason, the ready-state transition, inline delivery, the exact shape of the delivered receipt per destination provider, retry semantics, and that Sanity drafts are never published or deleted. This is exactly the mutation context an agent needs that the hint flags alone cannot convey.

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 prerequisite before the receipt details, and most sentences carry behavioral weight. It is dense and long-winded in the receipt enumeration, but that detail is genuinely useful for a no-output-schema tool.

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

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

With no output schema, the description compensates well by describing the delivered receipt fields, degradation reasons and failure behavior. The only meaningful omission is any description of the id parameter and the distinction between the two input fields.

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

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

The description never mentions the id or workspaceId parameters, so it adds nothing beyond the schema. With only 50% schema description coverage, the required id parameter is documented nowhere at all, leaving a real gap the description should have filled.

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

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

Names a specific verb and resource ('Approve one article: the human's act, in one call') and immediately scopes what approval means in this product. It distinguishes itself from siblings like run_gate, deliver_draft and delivery_status by stating it performs approval plus delivery in one act with no separate deliver step.

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 the precondition ('refuses unless the last run_gate check passed') and the intent ('record an approval the user gave explicitly'), which tells the agent when this tool is appropriate. It also clarifies that delivery happens inline rather than via a separate step, implicitly steering away from the deliver_draft sibling, though it never names that alternative outright.

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, and the description adds real context beyond them: the summary is persisted verbatim, re-approval moves the timestamp each time, and other tools gate on this call. It never explains why destructiveHint is set (what prior approval state is replaced), leaving a small gap for a write 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?

Front-loaded with the action, then each subsequent sentence earns its place: persistence semantics, downstream dependency, and re-approval behavior. No filler or repetition of 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?

For a 2-parameter mutation with no output schema, the description covers purpose, persistence, gating behavior, and repeat-call semantics. It stops short of describing permissions/auth requirements or what the caller receives back beyond the implied timestamp, which are minor gaps 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 50%, and the undescribed 'summary' parameter is exactly the one the description compensates for by enumerating its intended content (business, audience, voice, language, proposed topics) and stating it is stored verbatim. The workspaceId semantics are left to the schema, but overall this does more than the baseline of 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+resource: it records a human approval of their profile. An agent can immediately distinguish this from get_profile (read) and update_profile (edit) because the description frames the call as a committed approval record rather than a mutation of profile fields.

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 to call it: downstream tools (complete_onboarding, plan_topics, the quarter planner) refuse with profile-not-approved until it has been called once, and re-approval after a change is explicitly expected. It does not, however, contrast itself with the sibling update_profile, so no explicit alternative/exclusion is 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?

Adds substantial context beyond the annotations: nothing is deleted and body/brief remain readable via get_post, the confirm-gated dry run returns a specific degraded reason, archiving is idempotent (alreadyArchived), and danglingTopicLink signals a residual topic reference. This goes well past destructiveHint/idempotentHint.

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

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

Purpose and non-destructive guarantee are front-loaded, and every sentence carries distinct information (scope, dry run, idempotency, dangling link, alternative). The dense compound sentences with semicolons are efficient but border on cramped.

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 documents the return shape (dry-run fields: status, body presence, word count, calendar day) and result flags (alreadyArchived, danglingTopicLink). Nothing needed to invoke or interpret the tool 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 only 33% (workspaceId only), so the description must compensate. It thoroughly explains the confirm parameter's two modes but never explicitly defines id. It adds real meaning for confirm while leaving id contextually inferred.

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 (retire/archive) and resource (article) plus the exact scope of removal: queue, calendar, planner, link graph, and next_write. It distinguishes itself from the sibling unschedule_post by naming what that tool does instead.

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 tells the agent when to use this tool versus the alternative: 'Use unschedule_post to only free the calendar day.' It also explains the dry-run-vs-apply condition (confirm required to actually retire).

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: annotations say destructive=true/idempotent=true, but the description explains that nothing is deleted, that the row merely drops out of ranking/planning reads, that a repeat archive is not an error and keeps the original archivedAt, that hadMeasuredMetrics/hadBrief/linkage are preserved, and that the effect is fully reversible via add_topics. This is rich, non-obvious behavioral disclosure that the structured fields cannot carry.

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

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

Front-loaded with the one-line purpose before expanding into behavior. It is long, but nearly every sentence carries distinct, decision-relevant information (idempotency, reversibility, return fields, error case), with only mild redundancy around 'nothing is deleted' vs. the metric-preservation detail.

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

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

With no output schema, the description proactively documents the response surface (alreadyArchived, archivedAt retention, hadMeasuredMetrics, hadBrief, articlePostId, and the topic-not-found degradation). Combined with the reversibility and idempotency notes, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is only 50% and the undocumented 'topic' param carries the important semantics; the description supplies them by clarifying it accepts either a term or a topicId. It does not add much to workspaceId, which the schema already documents, so it falls short of a 5.

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

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

States a precise verb+resource: 'Retire one topic-bank question by term or topicId.' The agent immediately knows what is being acted on (a topic-bank question) and how it is identified, which distinguishes it from sibling tools like archive_post or merge_topics.

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 disappears from the reads that rank, plan, dedupe and re-measure, is reversible by re-adding via add_topics, and degrades with topic-not-found. It names add_topics as the undo path but never explicitly frames when an agent should archive rather than merge_topics or list_topics-first.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds what is returned (per-day occupancy plus post ids and statuses), but says nothing about pagination, timezone, or how the current workspace is resolved.

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 sentence with no wasted words, front-loading the verb and resource before the output shape.

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

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

With no output schema, the description does roughly cover the return shape, and annotations cover the safety profile. But it leaves the required year/month semantics undocumented and never separates this tool from 'list_calendar', which an agent needs in order to choose 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 only 33%: 'year' and 'month' carry no descriptions, and the description only hints at a single month. It adds no format, range, or semantics beyond the schema and does not compensate for the undocumented required 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 and resource ('Show a month of the content calendar') and describes the shape of the result (day occupied/free, post ids, statuses). However, it does not distinguish itself from the sibling 'list_calendar', which an agent could easily confuse with it.

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

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

There is no explicit when-to-use guidance, no prerequisite (e.g. which workspace), and no disambiguation from the near-identical sibling 'list_calendar'. Usage is only implied by the tool name.

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

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

Annotations already cover safety (readOnly, non-destructive, openWorld), yet the description adds substantial context: it reads only robots.txt, /llms.txt and home-page headers, so a CDN or firewall can still block an allowed bot, and it explicitly states there is no score. The honorsRobots semantics and bot grouping definitions are behavior an agent could not infer.

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

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

Front-loaded with the core purpose, then defaults, then the bots/findings semantics. It is long and packs several distinct ideas into run-on sentences, but nearly every clause carries needed meaning given there is no output schema.

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

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

With no output schema, the description carries the return-value burden and does so: it defines the bots groups (search/user/training), the honorsRobots flag, and the severity ordering of findings, plus what the tool cannot see. An agent has everything required to call and interpret it.

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

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

Schema coverage is 50% — url is undocumented in the schema, and the description compensates by explaining the url-omitted fallback to profile.siteUrl and the content-path derivation. workspaceId is already documented in the schema, so it needs no further elaboration.

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

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

States a specific verb and resource: which AI crawlers the site's robots.txt lets in, per bot, at the home page and at a content path. No sibling tool does anything comparable, and the scope (robots.txt/llms.txt/headers) makes it unmistakable.

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 calling it — without url it checks profile.siteUrl and the content path is the blog prefix import_sitemap detected — so the agent knows the defaults. It does not name exclusions or alternatives, but no sibling overlaps this function.

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?

Far exceeds the annotations, which only declare non-read-only, open-world, idempotent, non-destructive. The description adds determinism ('no model call'), cost estimates (~USD 0.115 / ~USD 0.004), the credentials-optional branch, the validated vs preview mode semantics, and the explicit caveat that dataConnected:false is not an error, and that a partial measurement still returns ready.

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 opening sentence is well front-loaded and states purpose, precondition and determinism. However the remainder is an undifferentiated block that mixes cost, auth branching, response vocabulary and field-by-field return documentation into dense prose, making it hard to scan; some of the measurement/signal field detail 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 and a complex, branching operation, the description carries the full burden and largely succeeds: it documents mode values, dataConnected semantics, the observed/unavailable/unmeasured vocabulary, the signals and firstBriefEvidence fields, and activationUrl. It is close to complete for an agent to interpret the result, with only minor ambiguity remaining.

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 a single optional parameter and a 100% schema description coverage, the schema already defines workspaceId's meaning and its runtime fallback. The description adds no further parameter-level guidance, 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 action (finishing setup/onboarding) and its completion conditions: profile fields populated and 12-15 search phrases stored via add_topics. It names related siblings (add_topics, submit_topic_analysis) so the agent can locate it in the workflow, though it never says explicitly how it differs from the other research/planning tools.

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

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

Gives a concrete precondition for calling it (profile complete + topics stored) and clearly partitions behavior by credential state (with credentials: measure + brief, mode validated; without: preview, no spend). It stops short of naming alternatives to use instead if the precondition is not yet met, so the agent must infer that gap.

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

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

With readOnlyHint/destructiveHint already covering safety, the description still adds a lot: credentials are always the user's own with no platform account, the password is never returned, 'free to call', and measurementAvailable=false degrades with reason missing-credentials mirroring add_topics. These are concrete behavioral facts an agent cannot get from the annotations.

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

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

Front-loaded with the connectivity answer, but the body is a single semicolon-chained run-on packing rate maps, rateSources, signal vocabulary and limits into one breath. It is dense and hard to scan, though for a tool with no output schema most of that content is load-bearing.

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

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

There is no output schema, so the description carries the full return-value burden and does so thoroughly — field-by-field meaning of balance, spend, signals vocabulary, limits and spentLast24h. An agent has everything needed to interpret the response.

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 optional parameter (workspaceId) and schema coverage is 100%, so the schema already documents it fully, including the current-workspace default. The description's 'this workspace' phrasing adds nothing beyond the schema; baseline 3.

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

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

The description states a specific resource — DataForSEO connection status plus account balance, spend, rates and limits — with concrete field names (balanceUsd, spentLast30d, measurementAvailable). It is unambiguous what the tool is, but it never explicitly distinguishes itself from siblings (e.g. refresh_metrics, check_ai_access), which all touch related measurement concepts.

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?

'Free to call' is useful cost guidance, and the degraded/missing-credentials clause hints at when the answer is unusable, but there is no explicit statement of when to call this versus a sibling or what to do with the result. Usage is only implied.

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

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

Annotations already declare the safety profile (readOnly=false, idempotent=true, destructive=true, openWorld=true), but the description adds substantial behavior on top: it never publishes/deletes, forces draft:true in git, overwrites the same path on repeat, handles slug changes via previousPath, patches only seodraft fields in Sanity, and enumerates degraded reasons (no-target, no-token, secrets-key-missing, github-error, sanity-error). This is exactly the added context the annotations cannot convey.

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 key differentiator (retry vs normal path) and prerequisites, and every sentence carries behavioral or return-value information. It is nonetheless a dense single block of ~1500 characters; some return-field detail could be tightened, though with no output schema much of it is load-bearing.

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 a mutation-style tool, the description carries the full burden and does so: it documents prerequisites, provider-specific behavior (github vs sanity), idempotency/overwrite semantics, returned fields (path, commitSha, htmlUrl, documentId, studioUrl, updated, pendingImageSlots), and the complete set of degraded reasons. An agent has everything needed 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 50%: workspaceId is documented in the schema but id has no schema description. The description only indirectly identifies the parameters ('one already approved article', 'the workspace's destination') without stating that id is the article identifier or clarifying workspaceId behavior, so it does not fully compensate for the undocumented id parameter. Baseline 3 is appropriate given partial schema coverage and only indirect param meaning in the description.

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

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

States a specific verb and resource ('Re-deliver one already approved article ... as a draft') and explicitly positions itself against the sibling approve_post, calling itself 'the retry and the re-send after an edit, not the normal path'. An agent can distinguish it from approve_post and upsert_post without opening any schema.

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

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

Gives explicit preconditions ('Requires the last run_gate check to have passed and the article to be ready (approve_post first)') and an explicit exclusion ('not the normal path'), plus the failure modes when the conditions are unmet (gate-failed, not-ready). Nothing about when to select this tool 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?

With readOnlyHint and destructiveHint already set, the description goes far beyond annotations by disclosing token non-disclosure, provider-specific return fields, live repository reads, dry-run writes, push permission checks, detailed failure reasons, and the null-when-unconfigured case. This is unusually rich behavioral detail.

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

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

The purpose is front-loaded in the first sentence, and the provider-specific detail is necessary given the absence of an output schema. The dense semicolon-heavy paragraph is information-rich but could be easier to scan, keeping it just short of a 5.

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?

Because there is no output schema, the description must carry return-value documentation, and it does so thoroughly for both providers, including check outcomes, permission fields, counts, and null configuration. Nothing essential for correct invocation or interpretation appears 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% for the single workspaceId parameter, and the schema already documents its fallback behavior. The description adds no syntax or format detail beyond the schema, 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?

The description states a specific purpose: reporting where a workspace delivers drafts and whether a provider token exists, with provider-specific fields. It clearly distinguishes the status/configuration role, but it never acknowledges or contrasts with siblings like deliver_draft, so an agent gets no explicit routing signal.

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 what information is returned but gives no explicit guidance on when to call this versus alternatives such as deliver_draft or list_workspaces. 'Free to call' is a cost note, not a usage condition, so the agent must infer the appropriate context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds the output shape (templates and headings for topic matching), but discloses no pagination, rate, or scoping behavior beyond what annotations provide.

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

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

Two compact sentences, front-loaded with what is returned and followed by the purpose. No padding, though the closing clause about headings partly restates the earlier field 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 correctly carries the return-shape burden by listing the fields, and the tool is a simple optional-param read. Only pagination or result-size behavior is absent, a minor gap for this read-only list 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?

The single workspaceId parameter is fully documented in the schema (100% coverage), including its default behavior. The description adds nothing about it, which is acceptable given the schema does the work, 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 concrete verb and resource ('List posts as internal-link targets') and enumerates the returned fields (id, slug, title, description, headings, template), which distinguishes it from the plain list_posts sibling by the linking purpose. It never names list_posts explicitly, so the differentiation is implied rather than foregrounded.

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 'so the next article can take a different shape' conveys the intent (picking internal-link targets before writing), which implies usage. There is no explicit when-not guidance and no alternative tool named, so it stays at implied context rather than 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 readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral/data context – that `brief` is null until upsert_post writes it, and that `serpBrief`/`customInstructions` are paid SERP research distinct from `brief` – but says nothing about errors (e.g. missing id) or the read's scope.

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 well with 'Get one post by id.' However, the middle sentences about brief/serpBrief/customInstructions are tangled and partly redundant ('separate from `brief`, the editorial plan' re-explains `brief`), making them harder to parse than they need to be.

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

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

With no output schema, field semantics are valuable, and the description does explain several returned fields. But it explains only a subset, gives no guidance on the `id` parameter, and omits any concurrency/error behavior, so a get-by-id tool remains only partially specified.

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%: workspaceId is documented in the schema, while the required `id` is undocumented. The description, however, spends its words on return fields (brief, serpBrief, customInstructions, standard) and adds no semantics for either parameter, so it fails to compensate for the gap on `id`.

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

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

States a specific verb and resource: 'Get one post by id.' Naturally distinguishable from list_posts (single vs many), but it never names or explicitly contrasts with any sibling, so the differentiation is left implicit.

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

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

There is no when-to-use or when-not-to-use guidance. The mention of upsert_post is only a note about when `brief` becomes non-null, not routing advice for choosing this tool over list_posts or get_profile. Usage must be inferred from the tool name 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 already establish it as a safe read (readOnlyHint=true, destructiveHint=false), and the description goes well beyond that: it explains the accepted/pending split, that profileApprovedAt is null until approve_profile runs, that siteInventory reflects the last import_sitemap, and that weakFirsthand is advisory-only and never alters status. That is rich domain behavior an agent cannot infer from annotations.

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

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

Purpose is front-loaded and the info density is high, but the description is bloated and partly redundant: the rule that citing a pending piece in brief.evidence 'fails the rules as evidence-unaccepted' is stated twice, wasting space. It is more repetition than an 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 return shape is entirely on the description, and it covers the profile's key structures (evidence bank, approval timestamp, site inventory, firsthand flag) thoroughly. For a read-only, single-optional-param 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 100% with a single optional workspaceId already fully documented in the schema (including the default behavior). The description adds no parameter-level 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 clear verb+resource: 'Read the workspace business profile.' The read orientation implicitly distinguishes it from the update_profile sibling, but it never names that alternative or explicitly contrasts them, so it stops short of full sibling 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?

Usage is only implied by explaining what the returned fields mean. It references approve_profile and import_sitemap as related concepts but does not state when to choose get_profile over alternatives or any preconditions for calling it.

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

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

Annotations already declare readOnly, non-destructive, and closed-world, so the safety profile is covered. The description adds content-level context about what the pipeline comprises (brief, evidence, rules), but says nothing about config freshness, whether the pipeline can be overridden, or what happens if none 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?

A single sentence with no filler that front-loads the verb and resource and then qualifies the return content. 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-param, read-only getter with no output schema, the description must at least signal what comes back, and it does (brief, evidence, rules). It is close to complete, with only minor gaps around the exact shape/limits of the returned pipeline.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-param tool applies. The description correctly does not invent parameter detail.

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

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

States a specific verb (Returns) and a specific resource (the seodraft write pipeline), and enumerates what the pipeline contains (brief, evidence, rules). It is readily distinguishable from the mutation/listing siblings, though it does not explicitly name a sibling it differs from.

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

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

Usage is only implied through 'used when drafting an article' — an agent can infer it is the config/pipeline fetch, but there is no explicit when-to-use vs. alternatives guidance and no mention of prerequisites or ordering relative to drafting 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?

Goes far beyond the annotations: no DataForSEO cost, never downloads pages, titles inferred from slugs (titleSource slug), off-host sitemapUrl refused, idempotent re-run semantics including pages dropping out, and explicit bounds (20 sitemaps, 5,000 URLs, ~25s) with partial status and sitemapsSkipped. Nothing here contradicts readOnly=false/destructive=true/idempotent=true; the removal-on-reimport note actually substantiates destructiveHint.

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, routing, and the cross-tool rationale are front-loaded, and almost every clause carries new information (cost, discovery order, bounds, failure tolerance). It is dense rather than bloated, though the single long paragraph could be broken up for scanning.

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 discloses the outcome shape (inventory updated, partial status, sitemapsSkipped) and the preconditions, limits, and dependency-free failure mode. An agent has everything needed to decide whether and how to call it.

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

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

Schema coverage is only 33% and the description compensates fully: it explains sitemapUrl's optionality plus the four-step discovery fallback, defines contentPrefix as the blog path with a detection default and an when-to-pass rule, and reinforces workspaceId scoping. These are semantics no structured field supplies.

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

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

States a specific verb and resource ('Read the site's sitemap into the workspace inventory of pages it already published') and ties it to a downstream sibling ('so add_topics can withhold a phrase an existing page covers'). An agent can distinguish this from add_topics or research_topic 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 tells the agent when discovery applies ('Without sitemapUrl it discovers...'), when to override contentPrefix ('pass it only when the detection is wrong'), a hard precondition ('Needs profile.siteUrl'), and whether failure matters ('carry on: nothing else depends on it'). This is unusually complete 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 tell the agent this is a non-destructive, idempotent write. The description goes well beyond that: it discloses the symmetry invariant ('linking B to A is the same call as linking A to B'), the shared cluster-id model, the exact degraded-reason taxonomy for refusals, and the `sharesSlug` return semantics with the hreflang caveat. This is exactly the behavioral context annotations cannot carry.

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

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

The core purpose and symmetry rule are front-loaded, and each sentence carries real information (prerequisites, refusals, return field). It is dense to the point of being a single long paragraph, and the closing hreflang/slug detail is useful but slightly tangential.

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 correctly supplies the return-value detail that would otherwise be missing (`sharesSlug` and its delivery implications). For a write tool with four distinct refusal paths and cross-tool prerequisites, the coverage is thorough.

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

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

Schema coverage is only 33% (only workspaceId is documented), so the description must compensate. It does so partially by establishing that the call takes two articles (id/alternateId) and that order is irrelevant ('linking B to A is the same call as linking A to B'), but it never explicitly maps id vs alternateId, leaving the agent to infer the roles.

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 ('Declare that two articles are the same article in two languages') and immediately explains the resulting model: a symmetric, shared cluster id. It is clearly distinguishable from its sibling unlink_translation, which it even references implicitly ('unlink the other side first').

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 prerequisites are given ('Both articles must already declare their own `language` with upsert_post; the workspace profile language does not count'), plus four named refusal conditions with reason codes (same-language, language-taken, language-unknown, archived) and the corrective action for language-taken. This is a near-complete when/when-not map for an agent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: exactly which fields come back and that 'article bodies and briefs are not included', which prevents an agent from expecting full content. Pagination behavior is not mentioned.

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, zero waste. The field list and exclusions are front-loaded, and the routing to alternatives follows 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?

No output schema exists, so the description must cover return values, and it does by naming the fields and stating the two exclusions. Read-only annotations cover the safety dimension. It stops short of pagination limits and the relationship to calendar_view, 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?

Only one parameter (workspaceId) and schema description coverage is 100%, so the schema already carries the full semantic load, including the default-workspace behavior. The description adds nothing further about it. Baseline 3 applies.

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

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

States a specific verb+resource ('List queue entries') and enumerates the returned fields (date, status, title, term), which distinguishes it from the article-oriented siblings. However, it never addresses the sibling calendar_view, and the 'queue entries' phrasing sits oddly against the name/title 'calendar', leaving a small ambiguity about scope.

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

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

Explicitly routes the agent: 'get_post returns one article and list_posts the full queue', giving a clear alternative and the condition that selects it. The distinction between this tool and list_posts is only implied (this appears to be the calendar-visible subset), and no guidance covers the calendar_view sibling.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaningful domain behavior: status filtering semantics, the rule that citing unaccepted evidence fails rules, and the 'Free to call' cost signal. It doesn't describe pagination or result ordering, keeping it from a 5, but it goes well beyond the annotations.

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

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

Two sentences are front-loaded with the return contents and then the status filter semantics. Every sentence adds value, though the second sentence is dense and could be split for readability. 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?

For a 2-parameter read tool with no output schema, the description supplies the necessary behavioral context: status filtering semantics, default behavior, and the evidence-acceptance rule. It omits pagination/ordering and workspaceId fallback context, which are minor gaps given annotations cover safety and the schema documents workspaceId.

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 status enum is defined in the schema, but the description adds real meaning: status omission defaults to returning everything, and the three enum values are contextualized with what each means for downstream rule checks. workspaceId is not described beyond the schema, but the main semantic parameter is 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?

The description clearly states a specific verb (list) and resource (evidence bank) and enumerates the returned fields (id, kind, text, source, adder, status, acceptance time). It doesn't explicitly contrast with a sibling tool, but the returned-field enumeration and 'evidence bank' scope make the tool's unique role clear enough that an agent can identify it.

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

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

Usage is implied by the status semantics: omitting status returns everything, and accepted vs pending vs rejected meanings are explained. However, there is no explicit when-to-use vs alternative guidance, and no statement of when NOT to use it (e.g., for a single evidence item). The guidance is adequate but not comparative.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds only the 'workspace queue' scope and says nothing about pagination, ordering, limits, or default workspace resolution, which is the main behavioral unknown for a list 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?

A single front-loaded sentence with zero filler. It is tightly sized, though arguably terse to the point of under-specification about what the listing contains.

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, annotated read tool with a fully documented optional parameter, the definition is minimally sufficient to invoke correctly. It falls short on distinguishing this list from sibling list views and on describing what is returned or how results are bounded.

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 optional workspaceId parameter is fully documented in the schema including the fallback behavior when omitted. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource with a scope qualifier ('List posts in the workspace queue'), which is clear. However, it offers no differentiation from siblings like get_post, list_calendar, or calendar_view, so the agent must infer which listing tool to pick.

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

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

There is no when-to-use guidance, no prerequisite, and no named alternative. The agent is not told when this is preferred over list_calendar or calendar_view, both of which also surface post-related data.

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

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

Annotations declare readOnlyHint=true, so safety is covered; the description adds real behavioral context beyond that: archived rows are filtered out and can be restored by re-adding the term, source=estimate means nothing was measured, and null reads as 'no exact-match volume reported' rather than zero. That is substantive disclosure an agent could not get from the annotations or 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?

Front-loaded with the purpose, which is good, but the remainder is a single dense paragraph of comma-spliced clauses about volumeStatus, aiVolumeStatus, agentAnalysis, previewRank and editorNote. The information is useful yet the run-on structure makes it hard to scan.

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 semantics itself and does so thoroughly for the key fields (volume statuses, source=estimate, agentAnalysis provenance, previewRank, editorNote). What it omits is pagination/limit behavior and the overall result shape, a minor gap for a read-only list tool.

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

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

Schema coverage is only 50% (workspaceId documented, archived bare), and the description compensates by fully defining archived's two-way behavior — omit to exclude retired questions, pass true to list only them. It does not restate workspaceId, but the schema already handles that side.

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 concrete verb+resource: list topic-bank questions together with the citability brief. It is clearly distinct from write-side siblings like add_topics, merge_topics or propose_topics, but it never explicitly contrasts itself with the other read siblings (list_evidence, list_posts), so it stops short of full sibling 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 only routing guidance is the archived branch: archived questions are excluded by default and archived: true lists only the retired ones. There is no statement of when to prefer this over suggest_topics/plan_topics/research_topic, so usage is implied rather than framed.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description's value is in the semantics it adds: which entry is the implicit default when `workspaceId` is omitted, and that archived workspaces are excluded from results. It does not mention pagination or ordering, which are the only remaining behavioral gaps.

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, front-loaded with what the tool returns, followed by the default-selection rule and the call-to-action. Every sentence removes a concrete ambiguity; nothing is 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?

With no output schema, the description carries the burden of describing the return shape and does so precisely (id, name, site URL, role, and the 'current' marker). It also covers the one exclusion rule an agent needs, leaving nothing essential to inference.

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

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

The tool takes zero parameters, so the baseline is 4. The description does add meaning about `workspaceId` — that omitting it falls back to the 'current' entry — though that parameter belongs to sibling tools rather than this one, so it stops short of a 5.

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

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

The description states a specific verb and resource ('The workspaces this account can open') and immediately enumerates the returned fields (id, name, site URL, caller's role), which distinguishes it from every sibling list_* tool. An agent knows exactly what this tool yields 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?

It gives an explicit trigger ('Read it first when the person works on more than one site') and an explicit follow-up action ('pass the id of the site they mean as `workspaceId` to every other tool'). That is genuine when-to-use guidance plus routing to downstream tools, not just context.

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 details dry-run semantics (same envelope, applied:false, nothing written, plan contents), the exact field-resolution rules for the survivor (fresher brief, measured-beats-estimate metrics, empty-field fill, article link, most advanced status), and that 'from' ends archived, never deleted. It also enumerates specific refusal errors (article-conflict, same-topic, topic-not-found, into-archived).

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

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

Front-loads purpose, then the dry-run behavior, then the merge resolution rules, then refusals — a sensible order. It is a single dense paragraph with heavy parenthetical nesting, and the metrics-fill detail is more granular than most callers need, so it is thorough rather than maximally tight.

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, yet the description still defines the returned plan shape and applied flag, plus all failure modes and the archive-not-delete outcome. For a destructive, non-idempotent merge tool, 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?

With only 25% schema coverage, the description carries the load: it explains that 'from' and 'into' are named by term or topicId, that 'into' is the survivor and 'from' the archived side, and that 'confirm' toggles dry-run vs real write. This fully compensates for the undocumented schema properties.

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 ('Fold one topic-bank question into another') plus the precise condition that triggers it ('when two phrasings are the same query'). An agent can distinguish this from archive_topic or add_topics without opening any schema.

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

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

Gives a clear when-to-use condition (duplicate phrasings of the same query) and thoroughly documents the dry-run vs confirm:true workflow and the refusal conditions that block the call. It does not name sibling tools (e.g. archive_topic) as the alternative path, so routing guidance is implied rather than explicit.

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

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

Annotations already establish readOnlyHint=true, so safety is covered. The description adds genuine behavioral detail: null is returned when nothing is scheduled, undated posts sort last, and three statuses are filtered out. The dangling clause about the 'standard' term being 'carried here' is opaque and slightly muddies rather than clarifies.

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 four sentences are tight and front-loaded with the selection and null-return rules. The trailing sentences about 'the term it returns' and 'standard' are confusing, undefined, and appear to carry context that does not belong in a tool description.

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

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

For a one-optional-param read tool with no output schema and annotations covering safety, the description covers return semantics (null, sort order, filtered statuses) well. The ambiguous 'term'/'standard' passage is the only real gap in an otherwise sufficient definition.

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 workspaceId parameter is fully documented in the schema, including its default behavior. The description adds no parameter-level information, so baseline 3 applies.

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

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

States a specific verb+resource ('return the next post to write') and immediately defines the selection rule: the earliest-dated post whose status is scheduled, with undated posts sorting last. An agent can distinguish this from list_posts and get_post without opening the schema.

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

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

Explicitly excludes statuses ready, writing and failed and reasons why, and routes the agent to list_posts for those. The final line implies this is the pre-writing call, but it never states a positive 'use this when you are about to start drafting' instruction outright.

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 (not read-only, not idempotent, not destructive), so the description adds real value: it discloses that citability briefs and the founder's angle are attached as writer instructions, that output splits into slots vs excluded with per-item reasons, and clarifies the 'beyond-slots' reason semantics. It does not cover permissions or re-run/idempotency effects, which matters for a non-idempotent write.

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

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

Front-loaded with the core action and three dense but purposeful sentences; everyDays and the return-shape details each earn their place. It is slightly run-on and the long final sentence could be split, but there is little waste.

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

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

With no output schema, the description usefully explains the return shape (slots/excluded vocabulary), which is a real strength. However, for a 6-parameter scheduling write tool it still leaves next, terms, and startDate undefined, and offers no guidance on how topic-bank input is sourced, so an agent cannot call it fully correctly from the definition alone.

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 17% (just workspaceId), so the description must compensate. It does explain everyDays well (gap between articles, 1=daily, 7=weekly, default 7) and hints at customInstructions via the founder's-angle note, but leaves next, terms, and startDate entirely 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 and resource: 'Schedule topic-bank questions onto the queue.' An agent can tell this writes to the calendar/queue rather than listing topics like list_topics. However it never contrasts itself with close siblings such as schedule_entry, add_topics, or propose_topics, so the boundary is inferred rather than stated.

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

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

The description says what the tool does but gives no when-to-use guidance, no prerequisites, and no alternatives in a crowded sibling set (add_topics, propose_topics, suggest_topics, schedule_entry). The reader must infer that this is the tool that places already-chosen topic-bank items onto the calendar.

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

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

Annotations only give readOnly/openWorld/idempotent/destructive flags, so the description's cost model (~USD 0.014 per seed plus an AI volume batch, ~USD 0.03 typical) and the enumerated degraded reasons (empty-profile, missing-credentials, spend-limit) add substantial context beyond what is structured. It even clarifies that spend-limit refuses before any request and charges nothing. It stops short of saying whether proposed topics are persisted into the topic bank or merely returned, and whether repeat calls re-charge.

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

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

The purpose is front-loaded in the first clause, and the cost and degradation sentences are dense but each carries actionable information (price estimate, remediation hints). The degradation sentence is a bit list-heavy but not wasteful.

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

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

With no output schema, the description carries the burden of explaining results, yet it never says what comes back (a proposed topic list? persisted topics?) though it does hint that ranking by AI search volume happens later, not in this call. Cost and failure modes are well covered, but the return behavior an agent needs is only implied.

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 workspaceId parameter is fully documented there, so the baseline is 3. The description does add the notion that the call is seeded by profile fields (business name and competitors), which gives useful semantic framing for what the tool consumes, but it says nothing extra about the workspaceId parameter itself.

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 (propose) and resource (topic-bank questions) plus the source signal (workspace profile business name/competitors via DataForSEO related keywords). It is clear on its own, but does not distinguish itself from close siblings like suggest_topics, plan_topics, or research_topic, leaving the agent to guess which topic-generation tool to pick.

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 guidance and no routing against the topic-generation siblings (suggest_topics, plan_topics, add_topics). The degraded-reason list hints at prerequisites (profile must be filled, DataForSEO connected) but frames them as failure modes rather than usage conditions.

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

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

Goes well beyond the annotations (which only flag destructive/expensive/non-idempotent) by disclosing concrete cost (~USD 0.11 per batch, priced per batch not per term), the 200-term overflow drop, the pre-spend refusal path with degraded:true and reason:spend-limit, and that archived terms are dropped before pricing so nothing is charged. This is exactly the operational context an agent needs before committing spend.

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

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

Dense and fairly long, but front-loaded with the action and cost, then layered with constraints; each sentence carries distinct operational information. No filler or repetition, though it 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 the meaningful return fields (refreshed, unmeasured, archived, spend object, degraded) and the failure semantics. Combined with the cost and cap rules, 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 50% (terms has no schema description), and the description compensates by defining what terms are measured, that the batch is capped at 200 with overflow reported, and how refreshed/unmeasured partition the input. workspaceId is left to the schema, so it isn't fully covered, but the description adds real meaning over 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 (re-measure) plus the exact resources measured (Google volume, AI search volume, intent) and the scope (topics already in the topic bank), and explicitly contrasts itself with the sibling family by being 'the only way to refresh measured metrics.' An agent can distinguish this from research_topic/add_topics without opening a schema.

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

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

Gives a clear usage condition ('only way to refresh measured metrics') and a hard prerequisite/caveat set: always batch, 200-term cap, spend-ceiling refusal, archived terms never re-measured. It does not name the alternative tool to use for brand-new topics, so the when-not boundary 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 already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so safety behavior is covered. The description adds the action (move article) and date format, but no additional context like auth needs, what happens to the previous schedule, or 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?

A single efficient sentence with zero waste, front-loading the core action and date format.

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 mutating tool with 3 parameters and sparse schema, the description is too minimal. It omits usage guidance, does not explain the required 'id' parameter, and provides no output or side-effect context beyond what annotations already state.

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

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

Schema coverage is only 33% (only workspaceId has a description). The description clarifies the date format as YYYY-MM-DD, but the required 'id' parameter remains completely undocumented, and no other param details are added.

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

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

The description states a specific verb (Move) and resource (article) and gives the date format. It is clear what the tool does, but it does not differentiate from siblings like unschedule_post or schedule_entry, and 'article' vs the tool name 'post' may cause slight confusion.

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 or alternatives are provided. The description does not indicate when to choose reschedule_post over unschedule_post, schedule_entry, or upsert_post.

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 mark destructive/open-world/non-idempotent, but description adds pricing, plan approval, spend-limit degradation with no charge/no storage, archived-topic refusal, 14-day cache, and AI Overview semantics. Rich beyond 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-loads the purpose, then layers cost, caching, and failure behavior without filler. Length is justified by the number of non-obvious operational traits.

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?

Includes brief contents, cost model, caching, failure reasons, and AI Overview interpretation. With no output schema, this gives the agent enough to call and interpret results.

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

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

WorkspaceId is documented in schema; description explains refreshMetrics' cost/effect and frames term as one question. With 33% schema coverage, it compensates for two of three parameters, though term format isn't specified.

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 'Build' and resource 'citability brief', and enumerates the brief's contents. The final clause 'refresh_metrics covers more than one term' implicitly distinguishes this single-question tool from the sibling bulk 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?

Clearly describes cost contexts, free cached briefs, refreshMetrics behavior, and degraded/refusal states. It does not explicitly state when to choose this tool over refresh_metrics, only that refresh_metrics handles more than one term.

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 idempotentHint=true and destructiveHint=true, and the description adds a useful behavioral note ('Does not mark ready') plus the two-layer evaluation model. But it never explains the destructive/'does not mark ready' tension or what state a run touches, which matters for a tool flagged destructive.

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

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

Purpose and the 'Does not mark ready' caveat are front-loaded, which is good, but the long embedded enumeration of every editorial rule is dense and largely duplicates what get_skill is said to contain, costing readability.

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

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

With no output schema, the description usefully hints at the return shape ('one list of findings') and covers the two rule layers. Combined with the pointer to get_skill and the no-output caveat, an agent has enough to invoke it, though parameter semantics remain thin.

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%: workspaceId is documented in the schema while id has no description. The description says 'a post' but never maps that to the required id parameter or explains scoping/fallback behavior, so it fails to compensate for the undocumented required 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 ('Check a post against the seodraft rules') and immediately scopes the work into two named layers (package rules, editorial rules), so an agent can tell it apart from siblings like approve_post or get_post. The closing 'Does not mark ready' sharpens the boundary further.

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 names the companion tool to read ('Read get_skill for what each rule wants') and implies the contrast with approve_post through 'Does not mark ready'. However it never states the trigger conditions explicitly (e.g., run this before delivery/approval), so usage context is clear but not fully specified.

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 the operation is a non-read-only, idempotent, destructive write, so the safety profile is largely covered. The description adds only the ISO date format hint and nothing about what the destructiveHint implies (e.g. whether an existing status is overwritten) or permission needs, so it adds modest value.

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

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

Two short sentences with the action front-loaded and no wasted words. It is terse to the point of under-specification rather than overly verbose.

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 annotations covering safety, the description is minimally adequate but leaves real gaps: what happens when date is omitted (schedule immediately?), what the required id refers to, and how this differs from the listing/rescheduling siblings.

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 33% (only workspaceId is documented), so the description carries extra burden. It usefully specifies the date format (YYYY-MM-DD), but says nothing about the required id parameter, leaving the most important parameter to 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?

States a specific verb and resource ('Set a post status to scheduled'), which is unambiguous on its own. However, it does not differentiate from close siblings like reschedule_post or unschedule_post, which an agent could easily confuse with it.

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

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

There is no guidance on when to use this versus reschedule_post, unschedule_post, or approve_post. The only usage-adjacent detail is that the date is optional, but no condition is given for omitting it or for choosing among the scheduling siblings.

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 far beyond annotations: it discloses idempotent-once-per-topic behavior, provenance handling (never mixed into observed numbers), the free/no-provider-call nature, and a full catalogue of refusal codes (unknown-evidence with degraded:true and unknownRefs, unsupported-finding, empty-analysis, topic-not-found, archived-topic) plus what happens on refusal (nothing stored, admissible evidence returned).

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

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

Front-loaded with purpose, then behavior, then usage. It is dense and long, but each sentence (refusal codes, evidence rule, preview mode) carries actionable detail rather than redundancy, so the length is largely earned.

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 complex, destructive, evidence-validating write tool with no output schema, the description covers the refusal surface, evidence contract, preview constraints, and provenance. Complete enough to invoke correctly, though the intent enum values and the exact shape of the success reply are 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?

With only 20% schema description coverage, the description carries the burden and does so well: it explains topic as 'a term or a topicId', the exact evidence-matching rule for gaps/angles and inside paaGroups, and the preview-mode restriction. It doesn't enumerate the paaGroups intent enum values, a minor 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 and resource: storing an agent-authored analysis of one topic's evidence (gaps, angles, PAA question groups). It clearly distinguishes itself from sibling tools like research_topic and complete_onboarding by being the only write path for inferred findings.

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: 'Used once per topic, after complete_onboarding or research_topic has produced the evidence to cite,' and clarifies the preview-mode case. It names triggering siblings but doesn't spell out a when-not alternative beyond the evidence prerequisites.

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

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

The description adds rich behavioral context beyond annotations: it discloses cost (~USD 0.03 per seed), external dependency on DataForSEO, and a specific degradation reason ('spend-limit'). This is critical for an agent to understand side effects and failure modes, far exceeding what the readOnlyHint and openWorldHint provide.

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

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

The description is three tight sentences with zero waste, front-loading the tool's purpose, then key parameter behavior, then cost and failure modes. 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?

For a tool with no output schema and 3 parameters, the description covers purpose, cost, dependency, and failure states well. It omits whether the suggestions are persisted or returned directly, and the seed parameter's expected format remains 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?

Schema coverage is only 33%, with 'keep' lacking a description. The tool description clarifies that keep=true merges into the topic bank, compensating for that gap. However, the seed parameter is undocumented in both schema and description, leaving its format or expected input unclear.

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

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

The description clearly states a specific verb and resource: it suggests related questions from a seed using semantic keywords and Google suggestions. It distinguishes itself from siblings like add_topics (which just adds) and research_topic by naming its source methodology.

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 'keep=true' instruction implies when to use the tool for merging versus not. However, there is no explicit guidance on when to use suggest_topics versus siblings like propose_topics or research_topic, which likely fill similar roles.

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 annotations: it clarifies that only the target article is affected, sibling articles remain linked to each other, and nothing is deleted — an important nuance alongside destructiveHint=true. It also confirms idempotency with the exact return flag (alreadyUnlinked: true), matching the idempotentHint annotation but enriching it with observable 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 short sentences, front-loaded with the core action and followed by the most decision-relevant details (scope of change and usage timing). No filler or redundancy.

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

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

For a simple two-parameter mutation tool with no output schema, the description covers the essential behavior, scope, idempotency, and usage guidance. The one gap is the undocumented id parameter, but its meaning is inferable from the tool name and schema.

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

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

Schema coverage is 50%: workspaceId is documented in the schema, but id has no description. The tool description does not explain either parameter or its format, so it adds no meaning beyond what the schema already provides. Baseline 3 is appropriate given the 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 (unlink) and resource (article from its translation cluster), making the opposite of the sibling link_translation immediately clear without naming it. An agent can distinguish this from related tools at a glance.

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

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

Gives an explicit when-to-use condition: 'Use it before changing an article's language to one the cluster already covers.' It does not name the alternative tool (link_translation) or state when not to use it, but the context is clear enough for selection.

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

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

Annotations already flag this as a non-read-only, destructive, idempotent mutation, but the description adds what the annotations cannot: the exact state transition (status back to writing, calendar day freed), what is preserved (body, tldr, FAQs, brief), and two named degraded-reason error codes for refusal. That is substantive behavioral disclosure beyond 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 core effect before the sibling routing and error cases, and every sentence carries information. Slightly dense as a single unbroken block, but there is no filler to cut.

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

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

For a 2-param mutation tool with no output schema, the definition covers state change, data preservation, refusal conditions, and sibling alternatives. Annotations cover the safety profile, so nothing an agent needs in order to invoke this correctly is missing.

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

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

Schema coverage is 50%: workspaceId is fully documented in the schema, while id is undocumented there and only implied by the description's references to 'the article'. The description adds no syntax, format, or fallback detail for the id parameter, so it neither compensates for nor worsens 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 precise verb+resource (take an article off the calendar) and immediately disambiguates against three siblings: schedule_entry (inverse), reschedule_post (for the held-day case), and archive_post (for retiring). An agent can pick correctly 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?

Explicit when-to-use and when-not-to-use, including the two refusal conditions (not-scheduled when a day is still held, already-unscheduled when a dateless draft) with the correct alternative named for each case.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds concrete behavior on top of that: pageKeywords 'replaces the whole list; send [] to clear it' and 'Evidence is no longer stored here.' These are genuine disclosures beyond the annotation flags, though the destructive semantics of the other 16 fields are 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?

The purpose is front-loaded, but the final sentence about add_topics withholding colliding topics is an off-topic tangent that belongs to a different tool and muddies the read. The description spends more words on evidence routing than on what the tool actually changes.

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 17-parameter, zero-required, destructive mutation with no output schema, the description covers only pageKeywords and evidence routing and omits what happens to the remaining fields. An agent cannot confidently invoke this tool across most of its parameters from the given text.

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 6% (just workspaceId documented), so the description must carry the burden. It explains pageKeywords well (format, path '/' as home, URL reduction, 50-pair limit, replacement semantics) but is silent on 15 of 17 parameters such as voice, audience, competitors, includeCta, articleStyle, and internalLinksMin, leaving most parameters semantically 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?

Opens with a specific verb+resource: 'Update the workspace business profile,' which cleanly separates it from read-side siblings like get_profile. However, the bulk of the text focuses on pageKeywords and evidence routing rather than conveying that 17 distinct profile fields are being updated, so the scope of the update is under-represented.

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 evidence concern elsewhere ('written with add_evidence and read from get_profile') and mentions add_topics withholding colliding topics, which gives some context about adjacent tools. But it never states when to call update_profile itself versus approve_profile or upsert_post, so guidance is fragmented and 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?

Goes well beyond the annotations (readOnly false, destructive true, non-idempotent). It discloses optimistic-concurrency behavior via version, the refusal condition for language changes on translation-linked articles, that brief is persisted before body, and the validation rules (no brief, <3 evidence items, evidence that never reaches the article).

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, the version guard, and the 'cannot mark ready' constraint before the denser language and brief explanations. Content is information-dense, though the language paragraph is a long run-on chain of clauses that 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?

For a 13-parameter, zero-required, nested-object mutation tool with no output schema, it covers the non-obvious semantics, validation blockers, and concurrency risk. Remaining gaps are the unexplained simple scalar fields, which are largely self-describing.

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 8% across 13 parameters, so the description must compensate; it does explain the highest-risk ones (language semantics and folder delivery, brief contents, version). It leaves title/body/slug/tags/date/faqs/tldr/description entirely to name inference, so the compensation is partial.

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

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

States a specific verb and resource ('Create or update a draft') plus a hard boundary ('Cannot mark ready'), which implicitly distinguishes it from approve_post. It also names siblings it is not (get_skill, get_post's serpBrief), though it never directly routes to a create-vs-update alternative.

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

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

Gives concrete operating conditions: pass version when updating, cannot mark ready, set language when the article is not in profile language, unlink first when a linked translation blocks a language change. Exclusions are stated clearly, but no explicit 'use X instead when…' routing across the sibling set.

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