Mark

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

Annotations already establish it is a non-read-only, non-idempotent, open-world mutation. The description adds genuine behavioral context beyond that: the two-phase upload handshake, the one-time client token, and the required second call to register the blob. It omits auth/permission requirements and error behavior, but the flow disclosure is meaningful.

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 information-dense sentences, front-loaded with the core action and then the mode-specific instructions. The trailing 'Related:' list is lightly useful for discovery but is the least load-bearing part.

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?

An output schema exists, so return values need not be described, and annotations cover the safety profile for this mutation. The description fully covers both invocation modes and the multi-step upload flow, leaving only minor gaps around permissions and failure handling.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds sequencing semantics the schema cannot: which parameters belong to the URL path versus each stage of the upload path, and that blobUrl/mime/size are supplied on the second (registration) call rather than the first. This is useful workflow context rather than mere repetition.

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 ('Adds media to the library') and immediately distinguishes the two operating modes (public URL import vs. file upload). It is clearly separable from siblings like search_assets, get_asset, update_asset, and delete_assets.

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 branching guidance: use source=url for a public https URL, use source=upload for a local file, and call again after the file is in storage. It names related tools but does not state when *not* to use this tool or how it relates to the post-authoring flow (save_post), so it stops short of full routing guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds genuinely new behavioral context: cost per view, that backlinks refresh incurs a paid fetch, and that non-refresh calls return a cached snapshot. Return format is left to the output 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 purpose and view enumeration, then cost, then refresh semantics, then related tools. Dense but every sentence carries information; minor redundancy in re-listing the view options already in the enum.

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

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

For a read-only analytics tool with a full output schema and 100% schema coverage, the description supplies the missing decision-relevant layers: view selection, paid refresh behavior, and cost. Nothing needed to call it correctly is absent.

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

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

Schema description coverage is 100%, so baseline is 3, and the description adds value beyond it by mapping cost to each view and clarifying refresh's paid-vs-snapshot trade-off. It also implicitly ties the url parameter to the page_keywords view. It stops short of detailing languageCode/locationCode defaults beyond the schema.

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

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

States a specific verb and resource ('Looks up any domain') and enumerates the four distinct views it can return. The parenthetical 'yours or a competitor's' clarifies scope, and the 'Related' line points at sibling territory so an agent can separate this from research_keywords/get_rankings.

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

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

Explains the key decision point for the refresh parameter (paid fresh fetch vs latest snapshot) and surfaces per-view costs, which materially guide invocation. However, it only lists related tools without stating when an agent should prefer research_keywords or get_rankings over this one, so no explicit exclusion guidance.

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

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

Adds behavior beyond the annotations: approved posts publish automatically at their scheduled time, there is no separate publish step, and a stale rev is refused. These are exactly the consequences (irreversibility, concurrency risk) an agent needs when annotations only give destructiveHint/idempotentHint flags.

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 action and input shape, then the publish semantics, then the usage gate, then related tools. No sentence is filler.

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

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

With an output schema and full annotations already present, the description covers the remaining gaps: auto-publish timing, absence of a separate publish step, stale-rev rejection, and the explicit-user-intent requirement. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and the nested rev/postId descriptions already state provenance from get_post or search_posts, so the description largely repeats the schema. It adds the consequence of a stale rev, which is useful but is behavioral rather than additional parameter syntax.

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 (approve) and resource (posts/revisions) and pins the input shape to [{postId, rev}]. It is clearly distinguishable from siblings like submit_post, review_post, and reschedule_post.

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 gates usage: 'Only use it when the user has explicitly asked to approve,' which is a real when-to-use constraint. It also names related tools (get_post, search_posts, review_post) so an agent can route correctly.

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

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

Annotations declare non-read-only, idempotent, non-destructive, but the description adds the key domain nuance: archiving is not a delete and the post remains in the workspace, plus which post states are ineligible. This is genuine behavioral context beyond the structured hints.

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

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

Four compact sentences, front-loaded with the core effect before the constraints and the routing hint. Every sentence carries distinct information with no filler.

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

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

A mutation tool with an output schema, annotations, and 100% parameter coverage only needs to supply effect semantics and eligibility constraints — both are present. An agent has everything required to call it correctly.

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

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

Schema coverage is 100% with both parameters described (postId, optional note), and there are no enums or nested objects. The description adds no syntax or format detail beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('Takes a post out of the publish path') and immediately clarifies the effect in domain terms. It explicitly distinguishes itself from delete_post and from sibling mutation tools, so an agent can route correctly without opening schemas.

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

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

Gives explicit when-not conditions: posts already live, queued to publish, or approved cannot be archived. It also notes re-invocation is a no-op and points to related tools (delete_post, review_post, search_posts), leaving little to inference.

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

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

Annotations already establish readOnly, idempotent, non-destructive and openWorld, so the lower bar applies. The description adds genuinely useful context beyond them: the ~30 second runtime (latency expectation) and that the check combines a live probe with PostHog data.

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

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

Two compact sentences, zero filler. The core purpose is front-loaded and the runtime plus related-tool pointers follow as supporting 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?

An output schema exists so return values need not be explained, annotations cover the safety profile, and the description supplies latency and method. What is only loosely covered is the boundary with get_ai_visibility, but the definition is otherwise sufficient to invoke correctly.

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

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

With a single parameter and 100% schema description coverage, the schema already explains siteId ('Site id from list_sites'). The description adds no further parameter meaning, so the baseline 3 applies.

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

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

States a specific verb (checks) and a precise object (whether ChatGPT, Perplexity and other AI assistants are tracked on a site), plus the mechanism (probe plus PostHog). This is clearly distinguishable from siblings like get_ai_visibility or check_site_readiness.

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 'Related: list_sites, get_ai_visibility' note implies list_sites supplies the siteId and that get_ai_visibility is the adjacent tool, but it never states when to prefer this tool versus get_ai_visibility or what preconditions apply. Usage is inferable 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 declare readOnlyHint, idempotentHint, openWorldHint and non-destructiveness, so the safety profile is covered. The description adds the per-call cost, which is real behavioral context an agent cannot get from the annotations, but omits anything about auth, rate limits, or side effects.

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

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

Three compact sentences, front-loaded with the core purpose before the cost and sourcing details. The terse 'Paid, about $0.004 per call' fragment earns its place as a decision-relevant fact.

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 an output schema present, the description needn't document return values, and it covers purpose, sourcing, and cost adequately. It is essentially complete for a one-parameter read tool, though a hint about how to interpret the audience-match result would fully close the loop.

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 parameter is already typed, so the baseline is 3. The description adds provenance value the schema lacks: the ID must come from list_saved_keywords, which tells the agent where to source it rather than just its type.

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

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

States a specific verb and resource ('looks at who currently ranks for a keyword') plus the decision it supports ('judge whether its searchers match your audience'). It also names adjacent siblings (list_saved_keywords, save_keywords, research_keywords), so an agent can place it relative to alternatives without opening schemas.

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

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

Gives concrete invocation context ('Pass a savedKeywordId from list_saved_keywords') and a cost signal ('Paid, about $0.004 per call') that helps an agent decide whether to call it. It stops short of explicit when-not-to-use or exclusion rules, so it lands just below the top.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds useful context beyond annotations by disclosing that it re-scans and specifying the readiness areas checked. It does not cover auth needs, runtime, or rate limits, but annotations reduce the burden.

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

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

Two short sentences, front-loaded with purpose and followed by a brief related-tools note. Every sentence earns its place with no repetition or 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?

The output schema exists and the annotations already cover safety behavior, so the description need not explain return values. It gives enough scope and component detail for a one-parameter scan tool, though it could better distinguish usage from sibling audit tools.

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

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

There is one required parameter, and schema description coverage is 100% with 'Site id from list_sites.' The description adds no parameter-level meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Re-scans a site for AI-agent readiness,' and lists the readiness dimensions (robots, llms.txt, structured data, speed). It is clear what the tool does, but it does not explicitly contrast itself with sibling audit tools such as run_site_audit or get_site_audit.

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 or when-not-to-use guidance. 'Related: list_sites, get_ai_visibility' names related tools, but it does not explain when this tool is preferable to alternatives.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false. The description usefully adds that the post's status is unaffected and that the comment is visible to the team, but it omits whether repeated calls stack duplicate comments or what permissions are needed.

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

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

Two short sentences, front-loaded with the action and its scope, then the key constraint and related tools. No filler or restated title.

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

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

With an output schema present and full annotation coverage, the description only needs to carry purpose, scope, and routing, which it does. Minor gaps remain around non-idempotent duplicate behavior, but nothing essential for correct invocation is missing.

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

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

Schema coverage is 100% and both parameters (postId, body) are fully described in the schema, including the length bound. The description adds no syntax, format, or targeting detail beyond what the schema already provides, 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 ('Adds a review comment to a post's current revision') and even scopes it to the current revision and team visibility. It names related siblings (get_post, review_post), so an agent can distinguish it without opening schemas.

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

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

Provides a clear negative condition ('Does not change the post's status') and points to related tools, which steers the agent away from misusing it as a status-change tool. It stops short of an explicit 'use this when...' rule or a named alternative for status changes.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so safety is covered structurally. The description adds genuine value beyond them: 'cannot be undone' plus the precise blast radius of removeFromDrafts ('published posts keep their copy'), which is behavior the annotations cannot express.

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

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

Three short sentences, no filler, with the destructive/permanent nature and the key flag behavior front-loaded ahead of the related-tool pointers. 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?

An output schema exists, so return values need not be described. For a two-parameter destructive mutation, the description covers permanence, the conditional side effect, and related tools, leaving nothing an agent needs in order to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3 for the two documented parameters. The description goes slightly beyond the schema by spelling out the consequence of removeFromDrafts on drafts versus published content, adding semantic meaning the schema text does not fully convey.

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

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

States a specific verb ('Permanently deletes') and resource ('assets'), with the permanence qualifier front-loaded. The 'assets' resource is clearly distinguishable from sibling delete tools (delete_post, delete_site, delete_strategy_item), so an agent can route without opening schemas.

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

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

The description names related tools ('Related: get_asset, search_assets') and explains what removeFromDrafts does, which implies when the flag matters. However, it never states when to use this tool versus the sibling deletes, nor any preconditions or exclusions, leaving usage context 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 declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, but the description adds what the agent actually needs: the operation is irreversible ('cannot be undone') and is gated on draft state, which is a precondition annotations cannot express. That is genuine context beyond the structured flags.

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

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

Three tight sentences: scope first, then the restriction plus the alternative, then irreversibility, closing with related tools. Every sentence earns its place and the disqualifying constraint is front-loaded where an agent will read it before calling.

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

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

For a single-parameter destructive mutation, the description covers precondition, irreversibility, and alternative routing; annotations cover the safety profile and an output schema exists so return values need no explanation. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and there is a single required postId param, so the schema already carries the semantics. The description reinforces that postId must reference an unsent draft, but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (permanently deletes) and resource (draft post) with the exact scope constraint: only drafts never sent for review. It explicitly distinguishes itself from archive_post by naming the point at which deletion stops being possible, so an agent can route 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?

Gives explicit when-to-use (unsent draft) and when-not (post in review, queued, or live), and names the alternative to use in the negative case ('call archive_post so it will not publish'). This is a full routing decision spelled out in the text.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the deletion is permanent, cannot be undone, and cascades to audits and readiness history. It stops short of naming auth requirements or a confirmation step.

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

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

Three short sentences, front-loaded with the action and its permanence, with zero filler. Every sentence earns its place: what it does, that it is irreversible, and related tools.

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?

An output schema exists so return values need not be described, and the description covers the destructive cascade and irreversibility for a single-param tool. It leaves mild ambiguity about whether other workspace resources (posts, keywords) are also removed, which matters for a permanent delete.

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

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

There is a single parameter with 100% schema description coverage ('Site id from list_sites'), so the schema carries the semantics. The description adds nothing beyond it, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Permanently removes a website') and scopes the blast radius to audits and readiness history, which distinguishes it from siblings like delete_post, delete_assets, and archive_post. An agent can identify the target of 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?

Usage is only implied by the irreversible deletion semantics; there is no explicit when-to-use statement or comparison against alternatives such as archiving or removing only the site's assets. The 'Related: list_sites, save_site' tail is a weak pointer rather than guidance on when this tool is the right choice.

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 readOnlyHint=false, so the safety profile is partly covered. The description adds important behavior beyond the annotations: deletion is permanent and cannot be undone, and deletion is refused for items still used by posts. It does not discuss permissions or idempotency on repeated deletes, but the added consequences and refusal condition are substantial.

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 short sentences, front-loads the permanent-deletion scope, then covers the buyer-question exception and refusal behavior. There is no filler or repetition.

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

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

Given an output schema, rich annotations, and 100% schema description coverage, the description contains everything an agent needs: what is deleted, what is forbidden, what is refused, irreversibility, and the relevant sibling alternative. No critical invocation detail is missing.

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

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

Schema description coverage is 100%, so id and kind are already documented in the schema, including the enum and the note that buyer questions cannot be deleted. The description repeats the affected kinds but adds no parameter syntax, format, or sourcing detail beyond what the schema provides.

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

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

The description states a specific destructive verb and resource ('Permanently deletes a persona, pillar, angle, market or KPI target'), enumerates the affected entity kinds, and distinguishes the tool from save_strategy_item for buyer questions. An agent can immediately tell what this tool does and what it does not handle.

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

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

It explicitly routes buyer questions to save_strategy_item with active:false, states that items still used by posts are refused, and names the related save_strategy_item alternative. This gives clear when-to-use and when-not-to-use guidance rather than leaving the agent to infer 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 flag destructiveHint=true, but the description adds the specific consequence an agent must know: disconnecting zernio removes every social account at once rather than one channel, and scheduled posts stop publishing until manual reconnection in the Mark app. That is exactly the kind of blast-radius detail annotations cannot express.

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

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

Front-loaded with the action, then the destructive scope, then the pre-flight call, then the limitation, then related tools. Every sentence carries distinct, actionable information with no filler.

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

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

An output schema exists so return values need no explanation, and the description covers the destructive scope, the recovery path, and sibling navigation. Nothing an agent needs to invoke this safely is missing.

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

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

Schema coverage is 100% and the single connectionId parameter is already documented as coming from list_connections, so the baseline is 3. The description gestures at provider discovery via list_channels but doesn't add format or validation detail beyond the schema.

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

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

States a specific verb ('Disconnects') and resource ('an integration'), and immediately scopes the blast radius for the zernio provider. An agent can distinguish this from list_connections, sync_connections, and update_connection_settings without opening any schema.

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

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

Explicitly names the pre-flight step ('call list_channels first'), states a hard limitation ('Connecting accounts cannot be done from the agent'), and lists related tools for navigation. Both when-to-use and what-this-cannot-do are covered.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so 'Does not change anything' is largely redundant repetition of structured data. The only added behavioral context is the 'once available' qualifier indicating answer-engine results may be absent initially, which is a small but genuine disclosure.

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

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

Two tight sentences, front-loaded with the primary purpose and followed by safety/routing info. No filler, though the 'Does not change anything' clause earns little since annotations already carry it.

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

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

With an output schema present, return values need not be detailed and there are no parameters to document. The description covers scope and read-only nature adequately; naming concrete alternatives with conditions would have closed the remaining gap.

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

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

The tool takes zero parameters, so the schema baseline is 4. The description's enumeration of returned sections adds light value about scope but there are no parameters whose semantics need explaining.

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 read verb ('Shows') and enumerates the resource contents (buyer questions, AI search volume, referral traffic, readiness, answer-engine results), so an agent knows what comes back. It also names related tools, giving partial sibling differentiation, though the broad multi-section scope makes it harder to distinguish at a glance from check_ai_assistant_tracking or get_search_performance.

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 'Related:' list points at refresh_ai_volume, save_strategy_item and check_site_readiness, implying this is the read-side counterpart, but no explicit when-to-use vs when-not conditions are given. The relationship is left for the agent to infer.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description still adds something the annotations do not: the shape of what comes back, including the cross-reference to posts that use the asset, which helps an agent judge whether this call answers its question.

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, zero filler, with the payload description front-loaded and the routing hint second. 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 one-parameter getter with full annotations and an output schema, the description covers identity, scope, and payload without needing to restate return values. Only the absence of explicit when-to-use guidance keeps it short of complete.

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

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

There is a single parameter with 100% schema description coverage ('Asset id from search_assets'), so the schema already carries the semantics. The description adds no format, sourcing, or error guidance beyond what is there, making 3 the correct baseline.

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 ('Opens') and resource ('one asset'), and enumerates the payload (preview URL, details, which posts use it). The singular 'one asset' contrasts cleanly with the sibling search_assets, so an agent can route without opening either schema.

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

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

The 'Related:' line lists search_assets, update_asset, and delete_assets, which implies the read-one-by-id use case, but it never states when to choose this over search_assets or what the prerequisites are. Usage is inferred rather than instructed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'Does not change anything' largely restates structured data. The description adds scope (what corpus is returned) but nothing about auth, caching, or freshness that the annotations don't cover.

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

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

Three tight sentences, front-loaded with the return scope followed by the call trigger and a related-tools pointer. No filler.

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

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

An output schema exists, so return-value detail is not required, and the description supplies the return scope plus a usage trigger. For a zero-param, read-only tool this is close to complete, with only alternative differentiation missing.

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

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

Zero parameters, so the baseline is 4. The description usefully characterizes the returned data domains, adding context about what the no-arg call yields.

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 and enumerates the domains returned (brand voice, visuals, personas, pillars, angles, markets, buyer questions, KPI targets), which is concrete. The 'Related' line names sibling tools but does not say how this differs from 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?

Gives an explicit trigger: 'Call it before drafting or reviewing.' That is clear actionable context. It has no when-not guidance or explicit alternative-selection rules, keeping it just below a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: content is sorted by time, includes open slots and per-channel fill counts, and times are in the workspace timezone.

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 purpose followed by input convention and related tools. No filler; every sentence carries information.

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

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

An output schema exists, so return values need no explanation. For a read-only, zero-required-parameter calendar tool, the description covers purpose, scope, input convention, timezone, and related tools completely.

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

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

Schema description coverage is 100% and the schema already documents both parameters, so baseline is 3. The description restates the week/date convention and adds the timezone detail, but it never mentions the 'from' alias parameter, so it adds only marginal semantics.

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

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

States a specific verb and resource ('Shows the publishing calendar') plus the exact scope ('for one week'), and enumerates what the response contains. An agent can immediately distinguish it from get_post or search_posts.

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?

Points to related tools (save_post, reschedule_post) and explains the input convention (pass any date in the week), implying a planning/scheduling use case. It lacks an explicit 'use this instead of X when...' exclusion, so it lands at 4 rather than 5.

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

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

Annotations already declare readOnly/openWorld=false/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context: where the rules come from and what happens when channel is omitted. It stops short of describing the return shape, but an output schema exists for that.

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

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

Three short lines, front-loaded with the purpose, then the usage trigger, then the omitted-param rule and related tools. No padding; each sentence carries information.

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

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

An output schema exists, so return values need not be explained. For a simple read-only, single-optional-param tool the description covers purpose, trigger, and default behavior adequately; only a hint about the returned rule structure is absent.

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

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

Only one parameter, and schema coverage is 100% with an enum and an inline description. The description restates the omission behavior already in the schema, adding no format or semantic detail beyond it. Baseline 3 applies when the schema does the work.

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

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

States a specific verb+resource (get format rules for a channel) and enumerates exactly what those rules cover: length limits, hashtags, links, media, tone. Naming the data source ('same source Mark's in-app writer uses') further disambiguates it from generic channel lookups like list_channels.

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

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

Explicitly says when to call it ('before writing a post'), what the omitted-parameter behavior is ('list the supported channels'), and routes to related tools (list_channels, save_post, get_brand_context). Both the trigger condition and the alternative path are 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 readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral context: the link is workspace-scoped, never carries tokens or secrets, and is only a handoff into the Mark app rather than an in-API connection. That out-of-band workflow detail is exactly what 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 return value and its security constraint; the workflow sentence earns its place. The trailing 'Related:' list of four siblings is mildly redundant given several are already named inline, but it aids routing rather than bloating.

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?

An output schema exists, so return values need not be explained, and the description covers the one parameter, the security constraint, and the follow-up workflow. An agent has everything needed to call this correctly and interpret what happens next.

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

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

Schema description coverage is 100% and the parameter description already covers 'connectionId from list_connections, or a channel such as linkedin.' The prose restates the same semantics without adding format, validation, or example detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Returns the in-app URL to connect a provider') and immediately scopes what the provider argument can be. It distinguishes itself from siblings by referencing list_connections' ids and channel names, so the agent can route correctly without opening another schema.

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

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

Gives explicit when-to-use and what-comes-next guidance: the connection itself happens in the Mark app, then sync_connections should be called, and for social channels list_channels reveals connection state. It also names related tools, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'Does not change anything' is largely redundant. The description does add genuine behavioral context the annotations cannot: that results include period-over-period comparison and KPI-target progress, which shapes how the agent should interpret the output. No auth, rate-limit, or pagination detail is given.

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

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

Two sentences, no filler, with the core reporting scope front-loaded ahead of the safety note and the related-tool list. Every clause carries information.

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

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

An output schema exists so return values need not be described, and annotations carry the safety profile; the description covers scope, breakdowns, comparison behavior, and routing hints. The only real omission is explicit when-to-use guidance against the named siblings, which is minor given the rest of the coverage.

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

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

Schema description coverage is 100%, so to/from/marketId/pillarId are already documented, and the description adds no syntax or format guidance for them. It does mention the reporting dimensions (channel, post, pillar, angle), which loosely corresponds to pillarId filtering and to what the output slices by, but this is marginal over what the schema provides.

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

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

States a specific verb and resource ('Reports how published content performed over a period') and enumerates the exact breakdowns returned: reach, engagement, clicks by channel, post, pillar and angle, plus period-over-period change and KPI progress. This clearly separates it from get_search_performance and search_posts.

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 disambiguates with 'Does not change anything' and lists 'Related: get_search_performance, get_calendar, search_posts', which implies the neighborhood of alternatives. However, it never states the condition under which an agent should pick this tool over those related ones — no 'use this when you want X, use get_search_performance for Y'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds genuine context by naming the content returned (current revision, approval history, claim flags), which tells the agent this is the source of truth for revision state before mutating callers.

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

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

Three tight sentences: payload first, prerequisite second, related tools last. Everything is front-loaded and no sentence is wasted.

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

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

An output schema exists, so return values need not be explained, yet the description still previews them usefully. For a single-param read tool with full annotation and schema coverage, nothing an agent needs is missing.

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

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

Only one parameter with 100% schema description coverage; the schema already explains postId and its origin. The description adds no syntax, format, or lookup guidance beyond what the schema provides, so the baseline 3 is correct.

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 (opens) and resource (one post) and enumerates the exact payload returned — current revision, channel fields, media, schedule, status, claim flags, comments, approval history. It is clearly distinguishable from siblings such as search_posts or save_post.

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

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

Explicitly states when to call it: 'Call this before approve_posts or review_post so you have the current rev,' and lists related tools. It does not state when NOT to use it (e.g. bulk retrieval vs search_posts), so it falls just short of a 5.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, idempotent), so the bar is lower. The description adds one genuinely useful nugget beyond annotations — that the call does not consume credit — which aids cost-aware selection, but discloses nothing else about execution or 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?

Two terse sentences with purpose front-loaded and the credit caveat immediately after. The trailing 'Related:' line is of marginal value but does not bloat the definition.

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

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

For a read-only, single-parameter tool with a full output schema and complete annotations, the description covers purpose and the credit constraint adequately. The only real gap is the absence of explicit routing to run_rank_check for a fresh check.

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 siteId is fully documented in the schema, so the baseline is 3. The description adds no parameter detail and never mentions siteId or the primary-site default.

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 (shows) and resource (tracked keyword positions) with clear temporal scope (now and over time), plus the 'winners and losers' framing. It distinguishes itself from research_keywords and run_rank_check implicitly, but never names a sibling, so it stops short of a 5.

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

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

'Does not spend credit' implies this is the non-charging read path versus a spend-credit check like run_rank_check, but that alternative is never named. The 'Related:' list points at list_saved_keywords and save_keywords, which are related rather than decision-driving alternatives, leaving usage 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine behavioral value beyond that by disclosing the analytical content returned: striking distance queries in positions 5-20 and anomalies. That is more than a restatement of annotations, though it says nothing about rate limits or result caps.

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 filler. The metric list and special-content disclosure are front-loaded before the prerequisite and related-tools pointer.

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 an output schema present, return values need not be described, and annotations carry the safety profile. The description appropriately covers prerequisites and notable content. It could be stronger by routing between itself and the ranking/performance siblings, but nothing critical to a correct call is missing.

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

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

Schema description coverage is 100% and the schema already documents the to/from date formats and the 28-day default. The description adds no parameter meaning beyond the schema, so the baseline of 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 (Reports) and resource (Google Search Console results) with the exact metrics returned: queries, pages, clicks, impressions, position. It differentiates itself partly from siblings by naming inspect_url and list_saved_keywords, but never mentions get_rankings or get_content_performance, which are the closest overlaps in the tool list.

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

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

Gives a prerequisite ("Requires a connected Search Console property") and points at two related tools, but never states when to pick this over get_rankings or get_content_performance. The agent must infer that this is the Search Console-specific path. Context 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 declare readOnlyHint, idempotentHint and destructiveHint=false, so 'Does not change anything' is largely redundant. The description does add genuine behavioral context though: it discloses that the return payload names the exact remediation tool per gap, including the UI-only fallback (get_connect_link).

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

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

Two sentences, front-loaded with the capability scope and the readiness statement before the remediation behavior. The prerequisite list is dense but each item earns its place as a checkable condition.

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?

An output schema exists and already documents returned gap details, so the description correctly avoids re-explaining return values and instead covers the prerequisite taxonomy and remediation routing. Nothing an agent needs to invoke a zero-param readiness check is absent.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No parameter-level guidance is needed or missing.

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 (checks readiness) plus the exact capability set being gated: keyword research, saving keywords, post submission, site audits. It also enumerates the concrete prerequisites (active market with DataForSEO location/language, site, brand profile, posting slots, connections), which lets an agent distinguish it from sibling check_site_readiness.

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

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

Explains the outcome of a gap ('Each gap names the exact tool to call, or get_connect_link for UI-only steps') and lists related tools, which routes the agent for follow-up. It does not explicitly say when this should be preferred over the sibling check_site_readiness, so it stops short of a full when/when-not statement.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), lowering the bar. The description still adds genuine workflow context beyond them: the async 'poll this after run_site_audit' semantics imply the audit is produced asynchronously and this is the retrieval step, which is not carried by any structured field.

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

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

Two tight sentences, front-loaded with the return contents followed by the workflow cue. Every clause earns its place with no 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?

An output schema exists, so the description needn't restate return values, and annotations carry the safety profile. What remains — what it returns, the polling workflow, and related tools — is fully covered for a single-parameter read tool.

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

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

Schema description coverage is 100% and the single siteId parameter is already documented as coming from list_sites. The description adds no format, syntax, or default detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Returns') plus the resource ('latest site audit') and enumerates what's inside it (score, issues by severity, prioritized fix plan). It also names the sibling it follows (run_site_audit), so an agent can distinguish it from related tools 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?

'Poll this after run_site_audit' gives clear context for when to call it, and 'Related:' points at adjacent tools. However it stops short of explicit when-not-to-use guidance or explaining how it differs from check_site_readiness, so it isn't fully differentiated from all 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?

Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description reinforces with 'Does not change anything.' It adds a useful trigger ('first in a session') but doesn't disclose return size or pagination, though an output schema presumably covers payload shape.

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

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

Three tight sentences: purpose/payload first, then trigger, then non-mutation note and related tools. The parenthetical payload list is dense but earns its place by telling the agent what it will get.

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

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

For a zero-parameter read with an output schema and full annotation coverage, the description provides everything needed: what it returns at a high level, when to invoke it, what it does not do, and which siblings handle adjacent needs.

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

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

Zero parameters, so baseline is 4. There is nothing to document and the description correctly implies a parameterless call with no filtering requirement.

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 ('Shows which Mark workspace you're acting in') and enumerates the exact payload (role, timezone, members, sites, integrations, per-channel status, attention items). An agent immediately knows this is a workspace-state read, distinct from the many list_*/get_* siblings.

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

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

Explicit guidance: 'Use it first in a session, or when switching tasks.' It also names the alternative for a related need: 'For which social accounts are connected and each channel's rules, call list_channels.' When-and-alternative routing is 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?

Annotations already declare readOnly/idempotent/openWorld/destructive, so safety is covered; the description adds the non-obvious cost trait ('Uses your Google quota') and enumerates the diagnostic fields returned. That is genuine context beyond the structured fields, though no rate-limit magnitude or failure behavior is given.

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 filler, with purpose front-loaded before the quota warning and related-tool pointer. Every clause earns its place.

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

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

With an output schema present, return values need not be explained, and annotations cover the safety profile. Purpose, cost, and related tools are covered; only explicit when-not guidance 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?

Single parameter with 100% schema coverage and a schema description that fully specifies the URL format and ownership constraint. The description adds no parameter detail, so baseline 3 is correct – the schema carries the load.

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

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

States a specific verb ('asks Google') and resource ('whether a page is indexed') plus the diagnostic outputs it returns (coverage, canonical, last crawl). This clearly separates it from the write-side sibling submit_urls_to_indexnow.

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 'Related: get_search_performance, get_site_audit' pointer gives soft routing context but never states when to choose this versus those tools, nor any exclusion conditions. Usage is implied rather than 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?

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower; the description reinforces safety ('Does not change anything') and adds non-obvious field semantics such as rulesSaved=false meaning the channel falls back to Mark's default rules. It does not add auth or rate-limit context, keeping it below a 5.

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

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

Front-loaded with the scope and the platform list, then the disambiguation, then a safety note and a Related line. Most sentences carry signal, though the field-mechanics sentence about posting slots is slightly dense and the Related list is somewhat long.

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?

An output schema exists, so the description need not explain return values, but it usefully pre-empts confusion by defining rulesSaved and the connection-vs-integration distinction. For a no-parameter read tool this is complete; little is missing beyond edge-case behavior.

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

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

Zero parameters, so the baseline of 4 applies. The description correctly focuses on interpreting output fields (rulesSaved, approval mode) rather than inventing parameter semantics.

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

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

States a specific verb and resource (list every social channel Mark publishes to), enumerates the platforms, and describes what each entry carries (connection status, approval mode, active flag). It also names the sibling it is not (list_connections) so an agent can route without opening either schema.

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

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

Explicitly says this is where to check whether a social account like a LinkedIn page is connected, and tells the agent that list_connections shows integrations instead, with the reason (all social accounts share one Social publishing row). Both the when and the alternative are 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond that: the Social publishing aggregation caveat and the fact that 'connectionId' is the provider name consumed by sync_connections, update_connection_settings, disconnect_connection and get_connect_link.

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

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

Content is front-loaded with what is listed, then the scoping caveat, then the clarifications. It is fairly dense and the trailing 'Related:' list is a bit listy, but every sentence carries signal.

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?

An output schema exists, so return values need not be described, and the description covers the aggregation subtlety and the cross-tool identifier semantics. The only minor gap is pagination or result ordering, which is not addressed.

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 still explains the semantics of the connectionId identifier that this listing surfaces and how downstream tools consume it, adding meaning beyond the empty schema.

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

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

States a specific verb and resource ('Lists integrations') plus the exact payload fields returned (health, last sync, failed jobs). It explicitly frames itself against the sibling 'list_channels', so an agent can distinguish the two without opening either schema.

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

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

Explicitly states what it does NOT show (individual LinkedIn/Instagram accounts) and names the alternative to use instead ('call list_channels for that'). It also clarifies that connecting happens out-of-band via get_connect_link and sync_connections, covering when-not and alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuinely new context: it clarifies this is a lookup that does not persist anything, and it names the shape of the returned data (locationCode, place name, country, languages).

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

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

Two front-loaded sentences with no filler: purpose first, then the non-persistence caveat and related tools. Slight redundancy in enumerating return fields that the output schema already provides.

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 an output schema present and rich annotations, the description needn't explain return format or safety. It covers purpose, the negative constraint (does not save), the resolution guidance, and sibling routing — everything required to invoke it correctly.

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

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

Schema description coverage is 100% with all three parameters documented, so the schema does the heavy lifting and baseline is 3. The description confirms 'place name (and optional language name)' — reinforcing that language is optional — but adds no format, matching rules, or limit semantics beyond the schema.

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

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

States a specific verb (searches) and resource (DataForSEO location and language catalog) and names the lookup key (place name, optional language name). It explicitly distinguishes itself from the market-saving flow via the sibling names set_up_market and get_setup_status, so an agent can tell it apart 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 clear context — use it to avoid guessing codes — and negates the wrong use case ('Does not save a market'). It routes to the related tools by name but never states the explicit trigger condition (e.g. call this before set_up_market to resolve a place), so it falls just short of explicit when/when-not/alternatives.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, idempotentHint, and openWorldHint=false. The description's 'Does not change anything' only repeats that safety profile and adds no new behavioral context such as pagination behavior, permissions, 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?

Two short sentences with no filler, front-loading what the tool returns before noting it is non-mutating and listing related tools. Every sentence earns its place.

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

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

With an output schema, rich annotations, and full schema coverage, the description does not need to explain return values or parameter details. It is nearly complete, though it could add a brief note on when to prefer this list over related keyword tools.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters, including pagination, query, source, audience, and tagNames. The description adds no parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource: lists saved keywords, and names the data returned (tags, exclusions, tracking status, latest rank). It also names related tools, so an agent can distinguish this read operation from save_keywords and get_rankings.

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

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

The description implies retrieval of saved keywords and names related tools, but it gives no explicit when-to-use guidance, no exclusions, and no condition for choosing this over alternatives. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description's 'Does not change anything' reinforces that but adds no new behavioral detail such as result size limits or ordering; with the annotation bar already met, this is adequate rather than rich.

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

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

Two short sentences with the concrete payload listed first and the safety note plus related tools second. No filler, and the most decision-relevant information is front-loaded.

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

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

An output schema exists, so return-value detail is not needed, and the description still flags what the listing contains. With no parameters and complete annotations, the only mild gap is the absence of explicit routing criteria against the two named related tools.

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

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

Zero parameters, so the baseline of 4 applies. The description correctly adds nothing about parameters, and there is nothing to clarify.

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

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

Specific verb+resource ('Lists your websites') and it names the payload fields returned (primary site, agent-readiness score, latest audit summary). It partially distinguishes itself by pointing at get_site_audit and check_site_readiness as related-but-different tools, though it never states explicitly what makes it distinct from them.

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?

'Related: get_site_audit, check_site_readiness' gestures at adjacent tools but doesn't say when to pick this list tool over them or when to drill into a specific site. Usage is implied rather than stated, so the agent must infer the routing decision.

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 it is not read-only, is open-world, non-idempotent and non-destructive. The description adds value beyond those by disclosing the pricing model and the failure condition (workspace not set up) with the corrective tool, which the annotations do not 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?

Two sentences, front-loaded with the purpose followed by cost, then the failure fallback and related tools. No filler; marginally dense but every clause carries information.

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

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

With an output schema present, return values need no explanation. The description covers the operation, its cost, and the recovery path, leaving little an agent would need before invoking 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?

The tool takes zero parameters, so there is nothing to document and the baseline is 4. The description correctly avoids inventing 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 and resource: 'Re-estimates how often your buyer questions are asked in AI assistants.' An agent can identify the operation clearly, though the description leans on the 'Related' list rather than a defining contrast to distinguish it from siblings like get_ai_visibility.

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

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

Provides clear context: this is a paid refresh costing ~$0.0001 per keyword, and it names get_setup_status as the fallback when the workspace isn't configured. It doesn't explicitly state when NOT to refresh versus reading existing estimates, but the cost and refusal path cover the main decision points.

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 readOnlyHint=false, so safety is covered structurally; the description still adds real value by disclosing that tracking history is destroyed along with the keyword and that the operation is irreversible. It does not mention permissions or partial-failure behavior.

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

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

Three short clauses, front-loaded with the action and the irreversible warning, with the related-tools pointer last. No filler.

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

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

Annotations cover the safety profile and an output schema exists, so return values need not be explained. The description covers what is destroyed and irreversibility; only minor gaps like permission requirements or scope limits remain.

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 with 100% schema coverage, so the schema fully documents savedKeywordIds. The description adds no syntax, format, or batching guidance beyond what the schema already states, making 3 the correct baseline.

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 ('Removes') and resource ('saved keywords and their tracking history'), which clearly separates it from delete_post, delete_site, and delete_assets. It names related siblings (list_saved_keywords, save_keywords) but does not explicitly contrast with the closest destructive alternatives.

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

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

Usage is implied by the resource and the 'Related:' pointer to list/save tools, but there is no explicit statement of when to remove versus archive or otherwise suppress a keyword. The 'cannot be undone' line is a warning rather than 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 cover the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower. The description adds real value beyond them by disclosing the consequence that an approved post will publish at the new time, a downstream behavior the annotations cannot express.

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

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

Two tight sentences plus a short Related line, with the core action and outcome front-loaded. No wasted filler; the trailing Related reference is compact and useful.

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?

An output schema exists, so return values needn't be explained, and annotations carry the safety profile. The description supplies the publish consequence and the future-time constraint, leaving little an agent needs that isn't already covered.

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

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

Schema description coverage is 100%, so the schema already documents both postId and scheduledAt (including the future-UTC-ISO constraint). The description's 'new future time' only echoes the schema, so baseline 3 is appropriate.

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

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

States a specific verb (Moves) and resource (a post) with the scope constraint of a new future time, so the agent knows exactly what it does. It doesn't explicitly differentiate from siblings like save_post or submit_post, though the 'Related' line offers partial routing.

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

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

The description implies usage by specifying 'a new future time' and noting the effect on approved posts, but offers no explicit when-to-use versus when-not, nor prerequisites (e.g., must the post already be scheduled). The related-tool references are passing pointers, not conditional 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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, yet the description adds non-structured behavioral facts: it is a paid call (~$0.01), results are ephemeral until saved, and there is a recoverable setup-refusal condition. These go 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?

Three tight sentences, front-loaded with purpose then cost, persistence, and recovery guidance. Every sentence earns its place; no filler or repetition of 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 an output schema present, return values need not be described. The description covers purpose, cost, persistence behavior, and failure recovery, which is everything an agent needs to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds little param detail and its "seed topic or URL" phrasing is slightly misleading since the schema exposes only a seedKeywords array with no URL parameter, which could confuse an agent.

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 ("Finds keyword ideas") plus the returned fields (volume, difficulty, intent) and the input shape (seed topic or URL). An agent can distinguish this from siblings like list_saved_keywords or check_keyword_audience 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 names the alternative for persistence ("Results are not saved until you call save_keywords") and a fallback path for failure ("call get_setup_status"). This gives clear when-to-use-this vs when-to-call-something-else 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 disclose the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds the admin-only authorization requirement, which is genuinely useful. However, it does not explain the consequence of the 'link' action — e.g. whether the external post is consumed or merged — which is the key behavioral question for a resolving/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?

Two tight sentences plus a short related-tools pointer; the primary purpose is front-loaded and every clause carries information (two outcomes, auth gate, id source).

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 an output schema, full annotation coverage, and 100% parameter documentation, the description only needs to supply purpose, auth, and routing. It does that well, though it leaves the post-link side effects unstated.

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

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

Schema description coverage is 100%, with the enum values and the targetPostId/externalPostId origins documented inline, so the schema carries the parameter burden. The description adds no syntax or format detail beyond it, making the baseline 3 appropriate.

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

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

The description states a specific verb (resolve) with the two distinct outcomes (keep as unmatched external post vs. link to an existing Mark post) and names the resource precisely. An agent can distinguish this from generic post tools like get_post or list_connections without opening the schema.

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

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

It gives a real prerequisite ('Admin only') and points to the sibling that supplies the input ('list_connections') plus get_post as related context. It stops short of an explicit when-not-to-use rule, but the context for invoking it is clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes further by spelling out consequences the annotations can't: 'A rejected post will not publish' and 'Requesting changes unlocks the draft for editing.' That state-change detail is genuinely useful. It stops short of noting retry/idempotency behavior or permission requirements, so not a 5.

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

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

Four short sentences, front-loaded with the two decision branches, then prerequisites, then the consequence, then sibling routing. Every sentence carries actionable content with no filler.

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

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

An output schema exists, so return values need no explanation, and the mutation's effects are covered by the description plus destructive annotations. For a 4-required-param review action, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, and the enum values and note/rev descriptions are already fully documented in the schema. The description's note that the rev must be 'current' largely restates the schema's 'Current rev from get_post', adding little new syntax or format guidance. 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 (sends a post back / rejects) and resource, plus the two mutually exclusive outcomes with their semantics ('changes_requested', 'rejected, final'). It also explicitly distinguishes itself from approve_posts, so an agent can route without opening schemas.

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

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

Names the alternative ('To approve, use approve_posts') and supplies the prerequisite ('Needs the current rev') along with the consequence of each branch. When-to-use and when-not-to-use are both 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 declare it as a non-read-only, open-world, non-idempotent operation. The description adds genuinely new behavioral context beyond that: it is a paid operation at roughly $0.0006 per tracked keyword with a stated provider and depth. It omits whether the refresh is async or how long it takes, so it stops short of a 5.

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

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

Two sentences, front-loaded with the action and schedule scope, followed by cost and routing. No filler; 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?

Output schema exists so return values need no explanation, and the description covers action, cost, and target selection. It leaves the execution model (async vs. blocking) unspecified, a modest gap for an on-demand job trigger.

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

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

Schema description coverage is 100%, so both parameters are already documented, giving a baseline of 3. The description reinforces the choice between trackerId and siteId, adding minor routing meaning but no format or constraint detail beyond the schema.

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

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

States a specific verb and resource ('Starts an on-demand rank refresh for tracked keywords') plus the distinguishing scope ('outside the weekly schedule'), which separates it from the read-only get_rankings sibling. An agent can identify the operation without opening the schema.

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

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

Explains when to use it (on-demand refresh vs. the weekly schedule) and how to select the target via trackerId from get_rankings or siteId. No explicit when-not to use or exclusions, but the routing guidance is clear.

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

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

Annotations already cover readOnly=false, openWorld=true, non-idempotent, non-destructive, but the description adds information annotations cannot express: the ~$0.075 cost, the asynchronous multi-minute latency, the requirement to poll for results, and the workspace-prerequisite failure mode. These are exactly the behavioral traits an agent needs before committing to the call.

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

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

Two sentences, front-loaded with purpose and cost, followed by the follow-up/failure routing. Every clause earns its place with no filler.

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

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

Cost, latency, polling, and the error-recovery path are all covered, and an output schema exists so return values need not be explained. The only minor gap is scope detail on what the audit covers beyond the supplied siteId, which the schema partially handles.

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

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

There is a single required parameter with 100% schema description coverage ('Site id from list_sites'), so the schema already carries the semantics. The description adds nothing about the parameter, which is the expected baseline when schema coverage is complete.

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 ('Starts a new crawl and audit of a site') and implicitly distinguishes itself from get_site_audit, which it identifies as the polling companion rather than the initiator. An agent can tell exactly what this does without opening the schema.

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

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

Explicitly tells the agent what to do after invocation (poll get_site_audit), what to do on failure (call get_setup_status if the workspace is not set up), and names related tools. This is genuine routing guidance covering both the success and error paths, not just an implied 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 cover idempotency and non-destructiveness, but the description adds genuinely non-obvious behavior: per-keyword cost (~$0.004 for the audience check), that new keywords default to tracked, that track=false or exclusion suppresses tracking, and that exclusion halts tracking. This is exactly the supplementary context annotations cannot express.

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

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

Two tight paragraphs, front-loaded with the core action and its bundled effects, then the cost caveat, then the error path and related tools. Every sentence carries information; only the cost parenthetical is slightly dense to parse.

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

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

An output schema exists so return values need no explanation, and annotations carry the safety profile. The description supplies cost, default behavior, and failure recovery, leaving little an agent needs before invoking it correctly.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds real meaning: it explains the semantic intent of exclusion ("a keyword whose searchers aren't the buyer") and that excluding stops tracking, which clarifies the excluded/track interaction beyond the field-level text.

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

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

The description states a specific verb and resource ("Saves keywords") and enumerates the bundled side effects (tags, exclusion, rank tracking) in one call, which clearly distinguishes it from research_keywords, list_saved_keywords, and remove_keywords.

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

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

It states when to use it (keywords from research or Search Console), names related tools (research_keywords, list_saved_keywords, set_up_market), and gives an explicit error-recovery route ("If this refuses because the workspace is not set up, call get_setup_status"). It falls short of a full when-not-to-use rule, but the routing guidance is strong.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false, and the description adds real value on top: it clarifies that the tool never submits or publishes, that locked posts fail with a clear error, and that the channel cannot be changed during an edit. It stops short of detailing permissions or how repeated creates behave, but the mutation scope and error behavior are well covered.

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

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

Front-loads the create/edit distinction and follows with prerequisites and routing in compact sentences. The trailing 'Related:' list is slightly listy but earns its place by naming the relevant siblings.

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 an output schema present, return values need not be explained, and the annotations carry the safety profile. The description covers mode selection, prerequisites, and follow-up actions; only edge behavior like partial-failure or concurrency handling is absent.

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

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

Schema coverage is 100% and the schema already documents create-vs-edit semantics for postId, the channel immutability rule, and null-to-clear for angleId/pillarId. The description largely restates the create/edit rule rather than adding new parameter detail, so the baseline 3 is appropriate.

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

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

States a specific verb and resource (save/creates a draft or edits one) and distinguishes the two modes via the postId condition. It also explicitly names what it is not ('Never submits or publishes'), separating it from siblings like submit_post and approve_posts.

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 rules: omit postId to create (channel required), pass postId to edit a draft or changes-requested post. It names the prerequisite (get_channel_rules first) and the follow-up alternative (submit_post to send for review), leaving little to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so the agent knows this is a non-destructive, repeatable write. The description adds the upsert framing, which is useful, but says nothing about permission requirements, behavior on an invalid siteId, or side effects on the primary-site flag. With annotations carrying the safety profile, this is adequate but not rich.

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

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

Two short sentences: the capability and field list come first, the upsert selector and related tools follow. Every clause carries information; nothing is padded.

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

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

With an output schema present, return values need not be described, and the 5 parameters are fully covered by the schema. The description covers the add/edit distinction and field scope, leaving only edge-case behavior (invalid siteId, effect of promoting a new primary) unstated.

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

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

Schema description coverage is 100%, so every parameter (including the nested capture object) is already documented in the schema. The description restates siteId's edit semantics and loosely renames 'domain' as 'hostname', adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

The description states a specific verb pair (adds or edits) and resource (a website), then enumerates the manageable fields (hostname, name, primary, lead-capture). It does not spell out how it differs from near-neighbours like update_asset or update_brand_profile, offering only a 'Related:' pointer list, so sibling differentiation is partial.

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

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

'Pass siteId to edit' explicitly tells the agent which branch of the upsert it is invoking, matching the schema's 'Omit to add'. The Related list routes the agent to list_sites for discovery and delete_site for removal, but there are no stated exclusions or prerequisites (e.g. what happens with an unknown siteId).

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 readOnly=false, idempotent=true, destructive=false; the description goes well beyond by explaining that active:false is a soft retire, that KPI targets reject the active flag, and that buyer questions are immutable in place. These are real behavioral constraints an agent would otherwise hit as errors.

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

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

Front-loaded with the core action, then layered constraints in short declarative sentences with zero filler. Every sentence carries a distinct rule, including the trailing Related pointer.

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

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

Covers creation, update, retirement, deletion routing, and per-kind exceptions; with an output schema present, return-value description is unnecessary. Nothing an agent needs 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 100%, so the baseline is 3; however the description adds conditional semantics the schema does not state, such as the KPI refusal of active and the buyer_question edit restriction, and reinforces id's create-vs-update role. It stops short of adding format/syntax detail for the kind-specific fields object.

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

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

States a specific verb pair (creates or updates) plus the exact resource (one strategy item) and enumerates the six valid kinds inline. An agent can distinguish this from save_post, save_keywords, or save_site 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 rules: pass id to update, omit to create, use delete_strategy_item for KPI removal, and buyer questions cannot be edited in place so must be recreated or retired. It also names related tools (get_brand_context, delete_strategy_item), leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'Does not change anything' largely restates structured data. It adds no new behavioral context such as pagination behavior, result ordering, or how cursor/limit interact, though the output schema carries nextCursor. With annotations covering the safety profile, a 3 is fair.

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 with zero filler; the core purpose is front-loaded and the sibling pointers come second. Nothing needs pruning.

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

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

For a read-only search with a full output schema and complete annotation coverage, the description covers enough to call the tool correctly. The only gap is the unsupported 'date' filter mention and no hint that results are paginated, both minor given the schema already documents limit, cursor, and nextCursor.

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

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

Schema coverage is 100%, so every parameter is already documented in the schema, including typo tolerance, the 20/100 limit default, and enum values. The description only gestures at the filter dimensions without adding syntax or semantics beyond the schema. Baseline 3 applies.

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

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

The description gives a specific verb ('Searches') and resource ('the media library') and enumerates the filter dimensions (text, type, source, date). It also names related siblings get_asset and add_asset. However, it claims a 'date' filter that no schema parameter supports, a small inaccuracy that keeps it from a 5.

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

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

It says 'Related: get_asset, add_asset' but never states the condition that selects this tool over those siblings (e.g., use get_asset when you already know the ID). Usage is only implied by the word 'Searches'. No when-not guidance or 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?

Annotations already cover the read-only/idempotent/non-destructive profile, and the description reinforces this with "Does not change anything." It adds genuine value beyond annotations by disclosing that each post's current rev is returned, which matters for downstream write calls. It does not mention pagination defaults/limits beyond what the schema states.

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 purpose, immediately followed by the highest-value usage hint, then related tools. No filler and nothing repeated from the schema.

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

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

For a read-only search tool with a full output schema, the description covers purpose, key routing, and the notable rev return value. It omits guidance on combining filters or pagination use, which would round it out but are not strictly required 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 description coverage is 100%, so all nine parameters are already documented, including awaiting_review being the review queue. The description restates the filter set without adding syntax, format, or interaction details (e.g., how from/to combine with status), so baseline 3 applies.

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

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

States a specific verb and resource ("Finds posts") and enumerates the filter dimensions (status, channel, date range, angle, pillar, text) plus the returned field (current rev). It is clearly distinguishable from get_post (single-post fetch) and search_assets (different resource).

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 routing instruction ("Use awaiting_review to open the review queue") and names related tools (get_post, approve_posts, review_post). It stops short of stating when NOT to use this tool or which sibling supersedes it for a given query shape.

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

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

Annotations cover the safety profile (openWorldHint=true, idempotentHint=false), and the description adds useful context beyond them: the recipient (signed-in user) and the payload (checklist of connections still waiting on the customer). It does not state delivery failures, rate limits, or that repeated calls re-send the email, which would fully earn a 5.

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

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

Two short sentences with the core action front-loaded and the sibling cross-reference trailing. No filler.

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

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

For a zero-parameter side-effecting tool with an output schema present, the description covers what happens and to whom. It omits when an agent should trigger it (e.g., after checking get_setup_status), a minor gap given the rich output 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?

The tool takes zero parameters, so baseline is 4. There is nothing for the description to clarify beyond what the empty schema already conveys.

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 (emails) and resource (checklist of connections waiting on the customer) with the recipient named as the signed-in user. The 'Related: list_connections' pointer distinguishes it from the sibling that merely enumerates connections.

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 'Related: list_connections' line implies this is the action variant of listing connections, giving implied usage context. However, there is no explicit statement of when to choose this over list_connections or get_setup_status, and no exclusions or 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?

Annotations already declare this is a mutation (readOnlyHint=false) that is idempotent and non-destructive. The description adds the genuinely non-obvious trait that saving a cadence has no immediate side effect ('never starts a check'), which is the key behavioral fact an agent needs. It omits permission requirements and return behavior, but the safety profile is otherwise covered.

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

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

Three tight sentences: purpose and enum values first, the non-obvious side-effect caveat second, then parameter routing and related tools. Every sentence earns its place with no 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 mutation tool with full annotation coverage, 100% schema coverage, and an output schema (so return values need not be described), the definition supplies the purpose, the behavioral caveat, and the per-check parameter routing. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds cross-parameter routing logic beyond the schema: it clarifies that rank accepts either trackerId or siteId while site_audit requires siteId, a relationship the per-field schema descriptions only imply.

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 ('Sets how often a rank check or site audit runs') and enumerates the possible cadence values. Crucially it separates itself from the run_* siblings with 'Saving a cadence never starts a check', so an agent can distinguish scheduling from triggering 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 concrete routing: pass trackerId from get_rankings or siteId for rank, siteId for site_audit, and names run_rank_check/run_site_audit as related tools. It stops short of an explicit 'use run_rank_check when you want to trigger a check now' exclusion, so it is clear context rather than full when/when-not guidance.

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

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

Annotations cover safety (idempotent, non-destructive, open-world), but the description adds genuinely non-structured behavior: it refuses and returns candidates rather than guessing when the place/language is ambiguous, and it updates an existing market for that location instead of creating a duplicate. Auth/permission requirements are unstated, and idempotency is only implied by 'updated'.

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

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

Front-loaded with the primary action, then the ambiguity fallback, then the update semantics, then a compact scope boundary and related-tool list. Every sentence carries distinct information; nothing is repeated from the schema or annotations.

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

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

With annotations and an output schema present, the description need not restate safety or return values, and it covers the resolution behavior and the ambiguous-input path. The main residual gap is the absence of any permission or account-precondition context for a tool that writes a market 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 coverage is 100% and every parameter already carries a description, so the schema does the heavy lifting. The description adds the notion that place/language are resolved to DataForSEO codes and that ambiguity is surfaced, but says nothing about priority or timezone semantics beyond what the schema states.

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

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

States a specific verb pair (creates/updates) and resource (an active market) plus the transformation it performs: resolving DataForSEO location and language codes. The 'Does not start a rank check' clause and the Related list separate it from run_rank_check and the read-only market 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 clear precondition (place + language, with an ambiguity fallback that refuses and returns candidates) and an explicit non-use case (it does not start a rank check). Sibling routing is only a bare 'Related:' list without conditions, so it stops short of full when/when-not guidance.

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

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

Despite annotations covering safety hints, the description adds rich behavioral context: auto-approval depends on channel settings and claim flags, publication occurs at scheduled time only if already scheduled and auto-approved, and the result indicates which path occurred.

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 uses four concise sentences. The 'Related' list is helpful but somewhat loose and could be trimmed, slightly reducing structural tightness.

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 an output schema present, the description need not explain return values, and it gives enough conditional and fallback detail for correct invocation. Annotations plus schema plus description cover the agent's needs for this mutation tool.

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

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

Schema coverage is 100% and the single postId parameter is fully described in the schema. The description implies that a draft is submitted but adds no syntax or format details beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb and resource: 'Sends a draft to review.' It clarifies the conditional auto-approval behavior, distinguishing it from sibling tools like approve_posts and save_post.

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

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

Explains the key conditional outcome (auto-approve vs. not) and gives a fallback: call get_setup_status if refused due to workspace setup. It also lists related tools, but does not explicitly say when to prefer this over save_post or approve_posts.

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