Mark

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

Annotations only declare the write/non-idempotent/open-world profile; the description adds genuinely useful behavioral context the annotations lack - the one-time token returned by the upload step, the required second call after the file reaches storage, and the constraint that PDFs become documents attachable to LinkedIn posts only. Missing details like token expiry or size limits keep it from a 5.

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

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

Front-loaded with the core action, then the mode-specific rules, then related tools - three tight sentences with no filler. Dense but every clause carries information; only slight comma-heavy phrasing costs a point.

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

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

For a 10-parameter mutation with an output schema (so return values need no explanation), the description covers the required two-step flow, mode selection, and the PDF restriction. Remaining gaps (auth requirements, size/type limits, token lifetime) are minor.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the field-by-field schema text by explaining cross-parameter sequencing: which fields go together for each source value and that blobUrl/mime/size are supplied on the second call. This adds conditional logic the schema does not express.

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

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

States a specific verb and resource ('Adds an image, video or PDF to the library') and immediately distinguishes the two operational modes (public URL import vs. upload start). An agent can tell what this tool does without opening the schema, and it names search_assets and save_post as related 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?

Explicitly says which parameters apply to which mode ('For a public https URL, pass source url plus url'; 'For a local file, pass source upload...'), including the two-phase upload sequence. It does not, however, state when to prefer this over update_asset or search_assets, so routing against siblings remains partly inferential.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the safety profile is covered. The description adds that body is required because claim quotes are checked against it, and that the tool returns a source id used downstream. It doesn't discuss failure modes (e.g., rejecting ambiguous text) but adds meaningful write-behavior context.

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

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

Front-loads the purpose, then the return value, then the routing and cross-references. Nothing is repeated; every sentence, including the Related line, 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?

Complete for a 3-param mutation tool with a 100% coverage schema and an output schema. The description covers purpose, required inputs, return value, and integration points without over-explaining.

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

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

Schema description coverage is already 100%, so the schema documents url, body, and title. The description reinforces that body is required and enumerates example content types, but adds no syntax or format constraints beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Adds a source to the Claims & sources page') and clarifies the domain concept by describing what a source is (pasted text like call notes, an audit, a spec sheet). An agent can distinguish this from save_claim, update_source, and delete_source 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 routing: use the returned id as sourceId in save_claim or as overlay evidence in update_brand_profile; to add a claim and its source in one call, pass source to save_claim. It names the alternatives and the conditions that select them.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real value by disclosing that overview/top_pages/page_keywords hit the provider for fresh data, that only 1 domain is processed per call, and that backlinks returns a cached snapshot unless refresh:true.

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 core purpose and view enumeration, followed by the two behavioral caveats. No filler, though the view list is largely mirrored by 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?

With an output schema present, return values need not be described; the description covers view behavior, freshness semantics, and related tools. It leaves minor gaps on location/language defaults and the siteId prerequisite, but is otherwise complete for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining what each view value does and how refresh interacts with backlinks specifically. It does not clarify languageCode/locationCode defaults beyond the schema text.

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

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

States a specific verb+resource ('Looks up any domain, yours or a competitor's') and enumerates the four views, so the agent knows exactly what the tool returns. It stops short of sharply distinguishing itself from siblings beyond listing 'Related' tools, so 4 rather than 5.

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

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

Gives clear context: use for domain lookups with one of four view modes, and the refresh semantics for backlinks. It names related tools (research_keywords, get_rankings) but does not say when to prefer those over this one, so no exclusion guidance.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, covering the safety profile. The description adds valuable non-annotation context — that this is a human-clicked UI path, not an agent path — but says nothing about blast radius, reversibility, or auth requirements.

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

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

Front-loaded with the purpose, then the restriction, then the alternative route — a logical order with no filler sentences. Mild redundancy in the trailing 'Related: approve_posts, get_post' line, since approve_posts was already named above.

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 fully covers purpose, the negative routing case, and the correct alternative, so an agent has everything needed to decide not to call it and what to call instead.

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 documented ('Post id', 'Exact rev the preview showed'). The description restates the exact-rev constraint but adds no syntax, format, or retrieval guidance 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 with scope: 'Approves one post at an exact rev.' It explicitly distinguishes itself from the sibling approve_posts by noting this variant is only reachable via a UI button, so an agent can tell them apart without opening either schema.

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

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

Gives explicit when-not guidance ('Agents never call it') and routes to the correct alternative ('to approve, use approve_posts, and only when the user has explicitly asked'). The condition that selects the sibling is spelled out, 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?

With annotations already declaring destructiveHint=true and idempotentHint=false, the description still adds substantial behavioral context beyond them: there is no separate publish step, outcomes vary by channel (social goes scheduled, email stays approved, LinkedIn Article waits on publish_by_hand), stale revs are refused, admins-only channels return skipped posts, and the handoff/stuck result is authoritative even if get_post lags 5 minutes. This is unusually rich 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?

The description is long, but it is front-loaded with the action and scope, then proceeds through channel-specific outcomes and failure modes in roughly descending importance. Some of the per-channel outcome enumeration overlaps with what the existing output schema would convey, which keeps it short of a 5.

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

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

For a single-parameter mutation tool with annotations and an output schema already present, the description covers everything an agent needs: input provenance, the no-publish-step model, per-channel end states, permission constraints, staleness handling, and where to verify results. Nothing material is missing.

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

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

Schema description coverage is 100% and the schema already documents postId, rev, and their provenance. The description's only parameter-level addition is that a stale rev is refused; otherwise the single param is fully covered by the schema, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource ('Approves the exact revisions given') and immediately scopes the input to [{postId, rev}]. It is readily distinguishable from siblings like review_post, submit_post, and get_post, which are called out by name as the source of rev and as related 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?

It gives a clear precondition/exclusion: 'Only use it when the user has explicitly asked to approve,' and states that rev must come from get_post or search_posts. It falls just short of 5 because it doesn't explicitly route the agent to an alternative action (e.g., submit_post) when approval isn't requested.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds substantial context beyond them: the post is retained in the workspace, re-calling is a no-op, non-draft posts are rejected, and CMS preview drafts may be deleted as a side effect. Minor tension worth noting: it discloses a genuine deletion ('deletes that preview draft') while destructiveHint=false, though that applies to the primary resource, so it does not rise to a contradiction.

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

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

Front-loads the core action and the not-a-delete distinction, then layers preconditions and edge cases. The length is defensible given the mutation semantics, permissions, and CMS interaction it must cover, though the CMS-preview sentence is dense and could be tightened.

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

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

An output schema exists, yet the description still explains the cmsPreview/review-note failure path, which is the piece an agent most needs to interpret a partial outcome. Combined with permission rules, idempotency, and preconditions, 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% with only two parameters, so the schema already carries the full parameter burden. The description adds a little meaning by referencing the post's 'review note' and the cmsPreview output field, but gives no additional syntax or constraint for note or postId beyond the schema text. 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 ('Takes a post out of the publish path') and immediately disambiguates from the most confusable sibling by saying 'this is not a delete.' The named related tools (delete_post, review_post, search_posts) let an agent place it in the toolset 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 enumerates when the tool will NOT act ('already live, queued to publish, or approved cannot be archived'), states the permission precondition for restricted channels (approverRole: approver), and names alternatives. This is as close to a decision rule as a description gets.

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/non-destructive, and the description reinforces this with 'Writes nothing' while adding genuine context: the per-channel composition of checks, the fail-vs-warn distinction and its blocking consequence, competitor_page-specific failures, and that exclusion matches carry the rule's reason. This goes well beyond the structured safety 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?

The purpose and non-saving behavior are front-loaded, and the trailing 'Related:' line is efficient. The dense parenthetical enumerations of checks are information-rich but heavy; a slightly tighter structure would read better, though little is wasted.

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

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

With an output schema present, the description need not describe return shapes, and it still covers result states, matched-text/field/position, workspace exclusion and claim sourcing, and cross-channel differences. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the assetIds usage condition (X thread media validated as 4 images / 1 video / 1 GIF) and ties meta to required_meta and get_channel_rules. That exceeds what the schema text alone 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 and resource ('Runs Mark's content checks on draft text without saving it') and enumerates exactly what is checked per channel, which cleanly separates it from write-oriented siblings like save_post and submit_post. An agent can distinguish this from save_post 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?

It tells the agent the outcome matters for submission ('A fail is what submit_post refuses on a draft; warnings never block'), and it names related tools (save_post, get_channel_rules, get_brand_context, list_claims), plus a condition for assetIds on X threads. It stops short of an explicit 'use this before calling submit_post instead of X' statement, so it is clear context but not a full when/when-not rulebook.

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld. The description adds value beyond them: 'Each call is 1 search' discloses a per-call cost, and 'that saves and tracks nothing' explicitly disambiguates the side-effect-free plain-keyword path.

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

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

Two sentences with the core purpose front-loaded, followed by a compressed related-tools line. Efficient overall, though the bare 'Related:' prefix lists tool names without explaining the relationship, which slightly weakens the closing line.

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 covers both input paths, market defaults, and side effects, leaving only the explicit this-vs-siblings routing gap.

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

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

Schema coverage is 100%, so baseline is 3. The description adds real meaning: savedKeywordId should come from list_saved_keywords, and a plain keyword uses the priority market unless both locationCode and languageCode are supplied. That interaction is not fully spelled out in the schema alone.

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: it fetches who currently ranks for a keyword and judges whether those searchers match the audience. The scope ('current Google top 10') is concrete, and it names related tools (save_keywords, research_keywords) so the agent can place it among siblings.

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

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

Gives explicit behavioral routing between the two input modes: pass a savedKeywordId from list_saved_keywords, or a plain keyword to look it up without saving/tracking. However, 'Related: save_keywords, research_keywords' does not state the condition under which the agent should prefer this tool over those 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=true, idempotentHint=true and destructiveHint=false, so safety and repeatability are covered. The description usefully adds which signals are evaluated, but says nothing about whether the rescan is synchronous, slow, or rate-limited — a real concern for a scan-triggering 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?

Front-loaded with the purpose and the scan scope in a single tight sentence; the 'Related:' sentence is short and adds some navigational value. Minimal waste, though the related-tools line 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 no explanation, and the scope of the scan is stated. What is missing is differentiation from run_site_audit/get_site_audit, which an agent selecting among readiness tools genuinely 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?

Only one parameter with 100% schema description coverage ('Site id from list_sites'), so the schema fully carries parameter meaning. The description contributes nothing beyond it, which is the baseline case.

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

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

States a specific verb (re-scans), resource (site), and enumerates the readiness dimensions checked (robots, llms.txt, structured data, speed). That is enough to distinguish it in kind from siblings, though it never contrasts itself with the similarly-named 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 'Related: list_sites, get_ai_visibility' line implies the siteId source and a neighboring visibility tool, and 're-scans' implies use after changes. But there is no explicit when-to-use/when-not, and no routing guidance against run_site_audit, the closest alternative.

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 the safe read-only, idempotent profile, yet the description adds substantial behavior: the default After/Before selection logic and defaultReason, the page-matching normalization (ignoring www., host case, trailing slash), and the fact that completed or partial runs including same-week reruns are all listed. This is well beyond what the annotations 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?

Purpose is front-loaded in the first clause and the dense paragraph carries real content (default logic, matching rules, output fields). It is somewhat run-on and long, but nearly every clause earns its place rather than 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?

An output schema exists, so return values need not be fully spelled out, yet the description still characterizes the compared fields (answer text, youNamed, competitors, cited pages, added/dropped/both). Combined with the default-resolution rules, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining the default Before run (last run before the live answer page was last published/pushed to the CMS, else the previous run) and the swap behavior. It reinforces rather than merely repeats 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 (compare) and resource (two stored check runs of one buyer question in one market) and scopes it per engine. It is clearly distinguishable from the singular sibling get_buyer_question_answers and from get_ai_visibility, which it explicitly names as related.

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 clause 'Reads stored checks only' implicitly routes the agent away from run_answer_engine_check and other run-triggering tools, and the default Before/After selection rules give concrete context. However it never states explicitly when to prefer this over get_buyer_question_answers or get_ai_visibility, listing them only as 'Related'.

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?

Far exceeds the annotations, which only mark it destructive/non-idempotent. It discloses what gets destroyed (review history, comments, performance logs; tracking links survive), the Zernio/CMS cancellation sequence, per-platform takeDown behavior, the Instagram/TikTok refusal, and the all-or-nothing failure semantics. This is exactly the irreversible-mutation context an agent needs.

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

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

Front-loads the core action and the irreversible warning, and every paragraph maps to a distinct behavior (default delete, CMS preview, takeDown, failures). It is long and dense, but the length is justified by the tool's cross-platform complexity, with little 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 destructive, cross-platform tool with an output schema, the description covers the remaining burden: permissions, the takeDown matrix, failure modes and their error reporting, and the preview-draft edge case. Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100%, so the schema already documents both parameters (baseline 3). The description adds real meaning beyond the schema: the default false behavior with the liveUrl outcome, the per-platform unpublish/delete sequence, and which platforms are refused.

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 deletes a post') and immediately enumerates the valid post states, so an agent knows exactly what it operates on. It also explicitly contrasts with archive_post, so it is distinguishable from its closest sibling without opening either schema.

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

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

Gives explicit when-to-use conditions (admin-only for published posts), when-not (external posts cannot be deleted; Instagram and TikTok cannot be taken down), and names alternatives (archive_post). The Related list routes the agent to the right 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 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?

Goes well beyond the annotations by disclosing irreversibility ('Cannot be undone'), a side effect the annotations do not capture ('leaves the source picker'), and two server-side refusal preconditions with the tools that verify them. This is exactly the extra context destructiveHint alone cannot supply.

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 verb and object, followed by refusals and a Related line. Dense but every sentence carries information; the trailing 'Related:' list is the only mildly extraneous element.

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 preconditions, irreversibility, and side effects an agent needs before invoking a destructive single-parameter tool. Nothing material is missing.

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

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

Schema description coverage is 100% and the sole parameter's description already says 'The note's id from list_claims', which the tool description merely echoes. No new syntax, format, or sourcing detail is added, 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 (deletes) and a narrowly-scoped resource (a pasted note, i.e. a source with type note), and explicitly excludes other source types. This distinguishes it from siblings like delete_post, delete_assets, and delete_site 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 when-not conditions: refusal while any claim quotes the note or brand profile evidence cites it, and states other source types cannot be deleted here. It points to list_claims and update_brand_profile as the places to check those conditions, but does not name where non-note sources are deleted.

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

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

Annotations already declare destructiveHint=true and non-idempotent, but the description goes well beyond them: irreversibility ('This cannot be undone'), the referential-integrity refusal conditions (angles using a persona/pillar, posts, answer-engine checks, AI-visibility results), and the fact that the error message names the blockers. This is exactly the extra context 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-loads the irreversible delete, then the refusal conditions, then the alternative — a sensible priority order with no filler. It is on the longer side and the refusal sentence is densely nested, but each clause carries distinct operational information.

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

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

For a destructive tool with full schema coverage and an output schema (so return values need not be described), this covers everything an agent needs: irreversibility, the failure modes it will hit, the workaround, and the 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?

Schema coverage is 100%, so both parameters (id, kind with enum) are already documented, including the id source (get_brand_context) and the buyer-question exclusion on kind. The description adds no format or value semantics beyond that, so it sits at the baseline rewarded by a complete 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?

Opens with a specific verb ('Permanently deletes') and enumerates exactly which strategy item kinds are affected (persona, pillar, angle, market, KPI target), immediately carving out buyer questions as non-deletable. An agent can distinguish this from save_strategy_item and the other delete_* siblings without inspecting the schema.

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

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

Gives explicit when-to-use and when-not: buyer questions can only be retired via save_strategy_item with active: false, and in-use items must be retired rather than deleted. It even names the remediation path (delete or move the dependent angles) when the refusal fires, 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 destructiveHint=true, but the description adds consequences they cannot express: zernio disconnection is all-or-nothing across every social account, scheduled posts stop publishing until each account is reconnected in the Mark app, and CMS disconnection leaves mapped channels with failing queued publishes. This is exactly the blast-radius detail an agent needs before invoking a destructive tool.

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

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

Front-loaded with the core action, then the two provider-specific consequences, then related tools. Dense and mostly waste-free, though the provider-specific warnings are split awkwardly across paragraphs and could be tightened.

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

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

An output schema exists, so return values need no explanation. The description covers the destructive scope, the downstream effects on publishing, and the related tools to consult — everything needed to call this correctly.

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

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

There is one parameter at 100% schema coverage, so the schema already documents connectionId as 'Provider from list_connections, e.g. zernio.' The description adds no new syntax, format, or constraint beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Disconnects an integration') and immediately scopes it against siblings by naming the affected provider (zernio) and the alternative tools (list_connections, list_channels, update_connection_settings). An agent can distinguish this from sync_connections or 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 tells the agent to call list_channels first to preview which social accounts would be removed, and states a hard boundary: 'Connecting accounts cannot be done from the agent.' That is a clear when-to-use, a pre-check alternative, and a when-not, all named.

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

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

With annotations present, the description still adds substantial lifecycle detail beyond them: a 90-day suppression window, restart-on-repeat semantics, the auto-resurface condition, and 'Changes only Mark, never the site' (which corroborates destructiveHint=false). Minor tension: repeat calls reset the clock, which nuances idempotentHint=true, but the disclosure is complete enough that an agent is not misled.

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

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

Four short sentences, zero filler, with the primary action and scope front-loaded before the edge-case behaviors. Every sentence carries information an agent needs to call it correctly.

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 two-parameter mutation with an output schema and full annotation coverage, the description supplies what remains: mutation semantics, duration, reversibility, and the source of the path value. Only error handling (e.g., path not present in the list) is unstated.

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

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

Schema coverage is 100% and both schema descriptions are already strong ('exactly as aiCrawler404s returns it', 'Site id from list_sites'). The description's 'one path' clarifies per-call cardinality but adds little beyond the schema; baseline 3 is appropriate.

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

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

States a specific verb (hides/dismisses) and a precisely scoped resource: one path in get_site_audit's aiCrawler404s and the Site health list, bounded to 90 days. The tool is unique among its siblings, and it explicitly names the related tool (get_site_audit) so an agent can place it in the audit workflow 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?

Establishes clear operating context: the path comes from aiCrawler404s output, re-dismissing restarts the window, and the entry resurfaces if it still 404s. 'Related: get_site_audit' points the agent back to the source workflow, though there is no explicit when-not-to-use or named alternative to skip.

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 mutation and idempotency; the description adds substantial behavior beyond them: marker/placeholder conventions, the '[confirm: …]' and unsourced-price rules, blocked-phrase failure saving nothing, no tables, content-check failure modes, refusal conditions, and an expected latency ('up to a minute'). The 'returns it and writes nothing' clause concretely explains the idempotentHint.

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

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

The behavior is front-loaded and almost every clause carries information, but the middle section is a dense run of semicolon-linked rules with nested parentheticals that take effort to parse. Given the tool's complexity the length is defensible, but it is not maximally scannable.

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, and the description covers everything else an agent needs: side effects, idempotent behavior, refusal cases, failure modes, follow-up tools, and timing. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description goes further by explaining what each enum value means (vs = '<you> vs <them>', alternative, pricing = what they charge and how you compare) and confirms competitorId comes from list_competitors. This adds real semantics beyond the bare enum list.

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

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

The opening sentence gives a specific verb, resource, and output artifact: 'Drafts a comparison page for one tracked competitor as a competitor_page draft post,' then enumerates the three kinds with their meaning. An agent can distinguish this from list_competitors or check_draft 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?

It states preconditions (competitor must be tracked/existing; refusal for unknown, untracked, or content-excluded competitors), a when-not path (if a live post of that kind exists, it returns it and writes nothing), and the next step (never submits – fix checks, then call submit_post). It also names related tools, including list_competitors as the source of competitorId.

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 earns credit beyond the annotations by disclosing the exact file layout, that each file carries the workspace name and export date, that the Brand section is marked unconfirmed, and that the layout is the one brand-interview reads.

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 key fact (what is exported and in what shape) is front-loaded, and the closer 'Does not change anything' plus the Related line route the agent efficiently. It is a dense single paragraph and the per-file inventory is long, but nearly every clause carries information an agent needs; only the read-only restatement 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 present, the description does not need to describe return shape, yet it still pre-summarizes the file contents. Between the description, the empty-but-required schema, and the annotations, an agent has everything needed to call this correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly spends no effort on argument 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 (exports) and resource (this workspace's context pack) and enumerates exactly what the output contains: four markdown files (company, customer, offer, voice) with the subject matter of each. An agent can distinguish this from get_brand_context or get_workspace without opening the schema.

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

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

Gives clear usage context: the files 'can seed another folder or workspace' and 'Edits belong in Mark, not in the files,' which tells the agent this is a one-way export, not an editing surface. It lists related tools (get_brand_context, update_brand_profile, save_strategy_item) but never states the conditions under which one should be chosen over this export, so explicit alternatives are missing.

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 readOnly/idempotent/non-destructive, so 'Does not change anything' adds little. However, the description discloses non-obvious behavior: inactive rows are included, null locationCode/languageCode markets are skipped by search checks, organizationJsonLd is null under specific conditions, and claims are the only facts drafts may assert. That is meaningful context 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?

The first sentence is well front-loaded, but the body is very long and dense with parenthetical field enumerations that largely restate what an existing output schema would carry. 'Does not change anything' is also redundant against readOnlyHint, so not every sentence earns its place.

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

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

For a zero-parameter read tool with full annotations and an output schema, the description is more than sufficient — it covers section semantics, error fields, active/inactive handling and inter-tool handoffs. Some of that overlap with the output schema is the only surplus.

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 per the rubric the baseline is 4. There is no input surface for the description to clarify, and it correctly adds none.

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

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

The first sentence names a specific verb (Returns) and resource (everything that shapes content), then enumerates the concrete sections (profile.voice, visual, overlay, offer) and related entities. It is clearly distinguishable from siblings like list_claims and get_content_performance, which it names explicitly as adjacent 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?

States the trigger plainly ('Call it before drafting or reviewing') and routes the agent to alternatives for specific needs: get_content_performance for KPI actuals, list_claims for retired claims and search, get_asset for the logo image. When-to-use and where-to-go-instead are both covered.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description adds real behavioral context beyond them: results reflect stored weekly checks only, and Claude/Perplexity answers come from APIs with web search rather than the consumer apps and may differ. It does not mention pagination or result limits, keeping it short of a 5.

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

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

The core purpose is delivered as one enormous run-on sentence with deeply nested parentheticals enumerating every return field (answer pages, youNamed, cited pages, baselines), which duplicates the existing output schema. Only the closing 'Also lists the weeks you can pick. Reads stored weekly checks only.' and Related line carry non-redundant value.

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 covering the safety profile, a 100%-covered schema, and a present output schema, the description is more than complete for correct invocation, and it adds the stored-only constraint. It is slightly over-complete on return values, which the output schema already 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?

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description reinforces that 'weekKey' comes from the listed weeks and that market defaults to the AI answers view, but adds little syntax or format detail beyond what the schema states, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('one buyer question's stored AI answers for one market and week') and enumerates the exact contents returned, so an agent knows precisely what this retrieves. The 'Related:' line names four siblings, letting the agent distinguish it from compare_buyer_question_answers and get_ai_visibility without opening a schema.

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

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

It gives a clear usage boundary with 'Reads stored weekly checks only,' implying live checks come from run_answer_engine_check, and the Related line points at alternatives. However, it never explicitly states when to choose this over compare_buyer_question_answers or get_ai_visibility, so the routing is implied rather than spelled out.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, but the description adds substantial context they can't: timezone is render-only and does not mutate stored data, and it discloses the handoff states (handing_off, stuck with reason and fix, publish_by_hand, publish_now) that appear on cards. This is behavioral detail well beyond structured fields.

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

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

Front-loads the core payload description before the handoff-state details, and each sentence carries information. It is dense rather than padded, though the handoff discussion is lengthy enough to slightly dilute the primary purpose statement.

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 listing tool with an output schema present, the description need not define return shape; it nonetheless covers scope, timezone behavior, slot semantics, and related tools. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including the 'from' legacy alias and the timezone non-mutation note. The description largely reinforces 'week can be any date in it' and repeats the render-only timezone semantics, adding only marginal meaning over the schema.

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

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

States a specific verb and resource ('Shows the publishing calendar') plus the exact scope ('for one week') and enumerates what it returns: scheduled/published posts, open slots with slot ids, and per-channel fill counts. An agent can distinguish this from list_* or get_post siblings 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 invocation guidance ('Pass week as any date in it'), explains the timezone rendering option, and names related tools (save_post, reschedule_post, update_posting_slots), notably that reschedule_post consumes the slot id this returns. It stops short of explicit when-not-use or alternative-selection rules.

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/idempotent/non-destructive, so safety is covered. Beyond that the description discloses concrete per-channel behavior the schema cannot express: X counts each link as 23, email returns subject (required) and preheader (optional) while Mark doesn't send email yet, linkedin_article returns title/cover over a Markdown body and Mark doesn't publish Articles, and the CMS mapping fields reported for website channels. Only minor gap is it doesn't note caching/freshness, but the behavioral disclosure is 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?

The purpose and the routing to get_drafting_guide are front-loaded, and the trailing Related list is compact. It is dense with channel-specific return detail (X/email/linkedin_article) that arguably duplicates the output schema, but each sentence carries usable signal and nothing is filler.

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

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

For a zero-required-param read tool with an output schema and full annotations, the description supplies everything an agent needs: what varies per channel, how to list channels, and which sibling to use for craft rules. Return values are further detailed, if somewhat redundantly with the 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?

Schema coverage is 100% and the single channel enum is fully documented with the omit-to-list behavior. The description reinforces the omit semantics but adds no syntax or format detail beyond the schema's own note, so the baseline 3 for a fully-covered single param 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 ('gives the format rules for a channel') and immediately scopes what those rules include (length limits, media ratios, meta field names/types). It explicitly distinguishes itself from get_drafting_guide on the craft-rules axis and from list_channels when no channel is given, 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?

Names the alternative explicitly ('For writing craft and this workspace's rules, call get_drafting_guide') and states the omit-channel branch that turns this into a listing tool. The condition selecting each behavior is spelled out rather than inferred.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely non-obvious data-provenance context: it enumerates the six engines and clarifies that Claude and Perplexity are queried through their APIs with web search, not the consumer apps, which affects how results should be interpreted. That is real disclosure beyond the structured fields.

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

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

The core (one competitor, this week's AI answers, by engine) is front-loaded and every clause maps to actual returned content. The heavy parenthetical engine list and the Claude/Perplexity caveat make it a dense single sentence, marginally harder to parse than ideal, but there is little outright waste.

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

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

With an output schema present, return values need not be spelled out, yet the description still characterizes them; combined with full 100% schema coverage and complete annotations, an agent has enough to invoke it correctly. The main omission is the lack of any guidance on choosing this versus get_competitor_scorecard.

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

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

Schema description coverage is 100%, so all three parameters (competitorId, languageCode, locationCode) are already documented in the schema, including defaults and the DataForSEO location type. The description adds no parameter-level syntax or format detail beyond that, 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?

The description names a specific resource (one tracked competitor's AI-answer detail), scopes it ('this week's AI answers, by engine'), and enumerates the concrete data returned (named/cited frequency, buyer questions where only the rival was named, rival-cited sites). It is far more than a restatement of the title. However, it only nods at the sibling with 'Related: get_competitor_scorecard' and never says how the two differ, so it falls short of clean 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?

'One tracked competitor' implies the prerequisite that the competitor must be tracked (echoed by the schema's 'from list_competitors'), which is a usable hint. But there is no explicit when-to-use, when-not, or condition distinguishing it from get_competitor_scorecard; the 'Related:' pointer names an alternative without saying which to pick. Usage is only implied.

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

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

Annotations already establish this as a safe, read-only, idempotent, non-destructive read, so the safety burden is lifted. The description adds real behavioral context on top: null means 'no answers or no data yet', the nextComparisonPage payload shape, its ordering logic (named-not-you first, then most keywords ranked, kind ordering within vs/alternative/pricing, pricing gated on a sourced price claim), and the content-exclusion caveat. It does not discuss caching or latency, but that is minor here.

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

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

The purpose sentence is well front-loaded, but the nextComparisonPage sentence is a single dense clause stacking ordering rules, kinds, and a pricing caveat that is hard to parse in one pass. The content largely earns its place, but the structure could be broken into shorter, list-like statements.

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

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

With an output schema present, the description need not explain return formats, yet it still clarifies the null semantics and nextComparisonPage semantics that an agent must interpret. Annotations, schema, and description together leave no obvious gap for correctly invoking this filtered read.

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

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

Both parameters (languageCode, locationCode) are fully documented in the schema at 100% coverage, including their priority-market defaults, so the schema carries the load. The description mentions 'one market' but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description names a concrete verb (get/compare) and resource (your sites vs each tracked competitor for one market) and enumerates exactly what the scorecard reports: AI answer naming/citation counts, organic traffic and keywords, and monthly ChatGPT/AI Overview mention share. It also draws the boundary against related tools (get_competitor_ai_detail, list_competitors), so an agent can distinguish this market-level scorecard from the per-competitor detail tool.

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

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

A 'Related:' line names get_competitor_ai_detail, list_competitors, and draft_competitor_page, and the scope note ('these cover your own buyer questions, not the whole market') implies when this view is appropriate. However, no explicit condition selects this tool over the alternatives, so the routing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, 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 cover the safety profile, yet the description adds substantive behavior: the kpis block ignores four of the input filters, actual is null vs { note } with a reason, period takes past/current/not_started, and engagement_rate values are percents. These are non-obvious traits an agent could not derive from annotations or schema.

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

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

Front-loads the core purpose in the first sentence and keeps every subsequent sentence information-bearing. The middle paragraph is a dense wall of text covering kpis semantics, which is justified by complexity but harder to scan than the rest.

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-value detail is not required, and annotations already carry the safety profile. Given the tool's complexity, the description still covers filter behavior, null handling, and value scales, leaving nothing essential for correct invocation unaddressed.

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

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

Schema coverage is 100%, so the schema already documents the four parameters (baseline 3). The description goes beyond it by explaining that from/to/pillarId/marketId are ignored in the kpis computation and by defining the semantics of a 'period' concept and the percent scale, though it leaves the exact interaction between the two modes somewhat implicit.

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 ('published content performed over a period') and enumerates the metric families returned (reach, engagement, clicks by channel, post, pillar, angle). It also names a sibling it relates to (save_strategy_item, get_search_performance), so an agent can distinguish it from other getters without opening the schema.

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

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

The 'Related:' line and the explanation that the kpis block mirrors the Targets page give clear context for when this tool applies, and the 'ignores from, to, pillarId and marketId' note warns the agent about a surprising interaction. However, it never states explicit exclusions (e.g. when to prefer get_search_performance or get_calendar instead), so routing is contextual rather than prescriptive.

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/idempotent/non-destructive, and the description reinforces that with 'Does not change anything.' It adds genuinely new behavioral context: the full inventory of what the guide contains and the guideVersion handoff contract to save_post. It does not cover failure modes beyond the schema's channel note, 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?

Front-loaded with the purpose, then the content inventory, then the routing rules and exclusions in short declarative sentences. Every sentence carries information an agent needs; nothing is padding.

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

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

An output schema exists, so return-value documentation is unnecessary, and the description still covers content, usage workflow, the save_post handoff, and the sibling exclusions. Nothing material is missing for correct invocation.

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

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

Schema description coverage is 100% and there is a single 'surface' parameter, so the schema already carries the meaning, including which channels lack a guide. The description only restates 'one channel' and adds no format or syntax detail beyond that, 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 ('Returns the drafting guide for one channel') and then enumerates exactly what the guide contains (honesty rules, channel craft, writing craft, brand voice, platform limits). It explicitly differentiates itself from get_brand_context, which holds claims and sources, so an agent can pick correctly without opening a schema.

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

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

Gives a concrete workflow: 'Check a draft against it before saving, then pass its guideVersion to save_post.' It also names the exclusion — claims and sources live in get_brand_context — and lists related tools, so both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: the comparison of the range 'against the same number of days just before it' and the connectivity prerequisite. It does not, however, address freshness, sampling, 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 tight sentences: the core capability and comparison behavior lead, followed by prerequisites, safety note, and related tools. No redundancy, 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 not be spelled out, and annotations carry the safety profile. The description covers the prerequisite, scope, and comparison behavior an agent needs to invoke it correctly.

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

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

Schema coverage is 100%, so both from/to parameters (including the default of the last 28 settled days) are already fully documented. The description's mention of a date range and comparison period is framing rather than added parameter semantics, 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 (Reports) and resource (Google Analytics organic search sessions, active users, key events, top organic landing pages) with a comparison window. It names related siblings (get_search_performance, get_content_performance) but never explains how this tool differs from them, so it falls 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 clear context: 'Requires a connected Google Analytics property' and 'Does not change anything,' plus points to related tools. However, it never states the condition under which an agent should pick this over get_search_performance or get_content_performance, so there is context but no explicit when/when-not.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description's 'Does not change anything' is largely redundant. What it adds is genuinely behavioral: each block explains why it is empty when it has no data, and the URL-format requirement warns that Search Console 'may find no rows' if the scheme or form is wrong.

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

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

The purpose and the block inventory are front-loaded in a single dense sentence, followed by the URL-format warning and the related-tools list. Nothing is padding, though the block enumeration is long and could have been tightened without losing routing value.

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 aggregation tool with a full output schema, the description covers the data sources, the empty-block behavior, the URL prerequisite, and sibling routing, so an agent has what it needs to call it correctly. The only minor gap is what happens when the URL falls outside the property beyond 'may find no rows'.

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 goes further on the critical url parameter by specifying the exact form ('scheme included') and the constraint that the URL must belong to the workspace's property. It leaves the date-range and compare parameters entirely to the schema, which is acceptable given full coverage.

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

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

States a precise verb and resource ('Reports everything Mark knows about one page URL for a date range') and enumerates the exact content blocks returned: Search Console metrics, tracked keywords, audit issues, posts, leads, buyer questions. This lets an agent distinguish it immediately from get_search_performance, get_site_audit, and get_rankings, which each cover only a slice of the same data.

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

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

Gives a concrete prerequisite (the URL must be on this workspace's Search Console property or one of its sites) and tells the agent to pass the URL exactly as get_search_performance returns it, scheme included. It closes with a 'Related:' list for routing, but never states when to prefer a sibling over this tool or when not to use it.

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

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

Annotations already declare the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds useful signal that results are comparative across time ('winners and losers'), but says nothing about timeframe defaults, data freshness, or aggregation granularity.

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 core purpose before the routing hint. Every clause earns its place, though the Related line is terse enough to be slightly ambiguous about intent.

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 the single parameter is documented, so the description needn't explain return values. Combined with annotations covering safety, what's present is nearly sufficient for correct invocation; only the timeframe/scope defaults remain 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?

Only one optional parameter (siteId) with 100% schema description coverage, so the schema already carries the semantics and the description adds no further detail. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb ('Shows') and resource ('tracked keyword positions') with the added scope 'now and over time, with winners and losers,' which tells an agent it returns a time-series comparison rather than a raw list. It nods at siblings via the Related line, but doesn't clearly distinguish itself from near-neighbors like get_search_performance or run_rank_check.

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_saved_keywords, save_keywords' line implies the surrounding workflow (view saved keywords, check their positions) but never states when to use this instead of get_search_performance or run_rank_check. Usage is inferable but not 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 read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real context beyond that: output is duplicated as markdown plus a fenced JSON block, is capped at the top 10 rows per section, and striking-distance analysis is limited to positions 5-20.

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

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

Three sentences, front-loaded with purpose and contents before output format, parameters, and prerequisites. The output-format sentence is dense but every clause carries information; 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?

Covers prerequisites, parameter pairing, output shape, and related tools for a 4-param tool with an output schema. Since an output schema exists, return values need no further explanation; the remaining gap is the absence of routing guidance against similar reporting siblings.

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

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

Schema coverage is 100%, so 3 is the floor, but the description adds meaning the schema lacks: compareFrom/compareTo produce prior-period totals, and 'from' defaults to the last 28 settled days is reinforced with intent. It explains the purpose of the comparison parameters rather than just their format.

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

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

States a specific verb (Reports) and resource (Google Search Console results) and enumerates the returned entities (queries, pages, clicks, impressions, position). It does not sharply distinguish itself from near-siblings like get_content_performance or get_ga4_organic_overview, though the 'Related' line names inspect_url and list_saved_keywords as adjacent 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 prerequisite ('Requires a connected Search Console property') and points at related tools, but never states when to choose this over get_content_performance or get_ga4_organic_overview, nor any when-not-to-use condition. Usage 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 cover safety (readOnly, idempotent, non-destructive, closed-world), and the description still adds substantial behavioral context: the null-audit-vs-error behavior, that dismissed paths are excluded, that recommendations do not change the score, that agenticReadiness is reported as 'N of M passed, never a score', and that dynamic rendering is misread as js_heavy. That is real disclosure an agent cannot get from structured fields.

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

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

A single unbroken block of roughly 500 words with no headings, lists, or paragraph breaks, mixing purpose, output semantics, edge cases and sibling pointers. Much of the return-value detail (render classes, check names, agenticReadiness states) restates what the existing output schema already encodes, and the density makes the important routing sentence ('Poll this after run_site_audit') easy to miss.

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 the tool's complexity, the description is more than adequate: it covers the no-audit case, the error case, scoring vs non-scoring checks, and pointers into get_brand_context and dismiss_ai_crawler_404. Nothing an agent needs in order to call this one-parameter read tool 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?

One parameter with 100% schema description coverage ('Site id from list_sites.'), so the schema already carries full meaning and the baseline is 3. The description adds no format, source, or validation guidance for siteId, and none is needed.

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

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

Opens with a specific verb and resource: 'Returns the latest site audit', then enumerates the payload (score, issues by severity, fix plan, aiCrawlerAccess). An agent immediately knows this is a read of an existing audit rather than a trigger. It lists related siblings at the end but never states the decision rule that separates it from check_site_readiness or get_brand_context, 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?

'Poll this after run_site_audit' gives a concrete temporal trigger, and the 'Related:' line names run_site_audit, check_site_readiness, get_brand_context and dismiss_ai_crawler_404. However, it only lists the alternatives without saying when each is preferred or excluded, and the tie-in with dismiss_ai_crawler_404 is only implied by the 'Dismissed paths are left out' sentence.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description adds real context beyond them: no email is sent, nothing is changed, empty sections return null, the upcoming list is capped at 10 with totalCount and manualCount, and the return shape is markdown plus a fenced JSON block with app links. It stops short of describing auth or workspace/timezone prerequisites.

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

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

The opening clause is well front-loaded and every detail is arguably load-bearing, but the body is one ~200-word sentence built from nested parentheticals, which makes it hard to parse and pushes key facts (the cap, null behavior) deep into the middle.

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 composite digest tool with an output schema, the description covers section-by-section content, the 7-day window semantics, null handling, list caps, return format and the no-side-effect guarantee. An agent has everything needed to call it correctly with or without weekOf.

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

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

Schema coverage is 100% for the single weekOf param, so the schema baseline is 3. The description goes further by scoping the parameter's effect: weekOf selects only the Search Console comparison days while review posts, keywords and AI checks are always current, which the schema does not say.

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

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

The description names a specific resource (the Monday weekly brief delivered by email) and enumerates its four sections plus the suggested actions, so an agent knows exactly what it returns. Differentiation from siblings is only gesture-level via the trailing 'Related:' list rather than a condition-based contrast with get_search_performance/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?

Usage is implied rather than stated: 'Related: get_search_performance, get_ai_visibility, search_posts' points at the component tools, and 'weekOf picks the Search days; posts in review, tracked keywords and AI answers are always the current ones' clarifies scope. But there is no explicit 'use this when you want the digest; use X instead when you want only…' routing, so the agent must infer when this digest beats its 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 already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered; the description reinforces it with 'Does not change anything.' It adds real value beyond annotations by disclosing the return payload and the mcpUrl connector nuance, though it says nothing about response size or cost.

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: the resource and its payload lead, then usage, then alternatives. The first sentence is long and parenthetical, but every clause earns its place and nothing is redundant 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 not be explained, yet the description goes further and helps the agent interpret them. Combined with usage guidance, sibling routing and a no-side-effects statement, nothing an agent needs to call this correctly is missing.

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

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

Zero input parameters, so the schema has nothing to describe and there is no risk of misuse. The description adds meaning by framing the parameterless call as a session-context snapshot. Baseline 4 applies for a no-parameter tool.

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

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

States a specific resource (the Mark workspace) and enumerates the concrete contents an agent gets back (role, timezone, members, sites, integrations, channel status, attention items, mcpUrl). It also names the siblings it is not (list_channels, get_website_cms) and the conditions that select each.

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

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

Explicitly says when to use it ('first in a session, or when switching tasks') and routes alternative needs to specific siblings: list_channels for connected accounts/channel rules, get_website_cms for blog/FAQ/competitor pages. When-not guidance is implicit but the routing is unambiguous.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely useful non-schema context: the operation consumes Google quota, which affects call budgeting.

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

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

Two tight sentences with the core purpose front-loaded and the quota caveat and related-tool routing trailing. No wasted words.

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 annotations carry the safety profile. The description supplies the quota context and sibling relations, leaving only explicit when-to-use guidance as a 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?

With a single parameter at 100% schema description coverage, the schema fully documents the 'url' argument including the property constraint. The description adds no syntax or format 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+resource ('Asks Google whether a page is indexed and why or why not') and enumerates the returned facets (coverage, canonical, last crawl). It is clearly distinguishable from siblings like get_site_audit and 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?

Names related tools (get_search_performance, get_site_audit) but never states when to prefer this tool over them or any exclusion conditions. The 'Uses your Google quota' note implies a cost consideration but does not guide tool selection explicitly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered; the description usefully reinforces this ('Does not change anything'). It adds genuine behavioral context beyond annotations: rulesSaved semantics (false = running on Mark's default rules) and that the timezone parameter only affects rendering, not stored data.

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

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

Front-loads the core resource and its returned fields, then layers differentiation and routing. The parenthetical enumeration of slot fields (weekday, local time, UTC instant, slot id, workspace timezone) is somewhat verbose given an output schema exists, but overall the text is dense rather than 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?

For a read-only, single-optional-param list tool with both annotations and an output schema, the description covers everything needed: returned fields, special-case semantics (rulesSaved), parameter side-effect profile, and routing to related tools. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the single timezone parameter is fully documented in the schema (IANA zone, no data mutation, defaults to workspace timezone). The description restates this rather than adding new syntax or edge cases, so the baseline 3 is appropriate.

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

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

States a specific verb+resource ('Lists every social channel Mark publishes to') and immediately distinguishes itself from the closest sibling ('list_connections shows integrations instead'). An agent can tell what this returns and how it differs from the alternatives 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 when to use it ('This is where to check whether a social account such as a LinkedIn page is connected'), names the alternative (list_connections), and routes to further siblings (list_pinterest_boards, get_connect_link, update_posting_slots). Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real domain behavior: retired claims are kept (retiredAt) because citing posts retain wording and a retired claim never reactivates, plus hasText meaning a textless source cannot back a quote. The line 'Does not change anything' only restates readOnlyHint, slightly diluting the added value.

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

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

Purpose is front-loaded and the sentences are information-dense, each carrying distinct semantics about claims, sources, and filtering. It runs long relative to a simple list tool, but little is wasted.

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

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

An output schema exists, so return values needn't be described, and the description still covers the data model (claim fields, source fields, active/retired lifecycle) and all filtering paths. An agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further: it says query searches claim text, quotes, source titles, links and body text, and that sourceId returns the source's full text in body with only its claims. That clarifies the effect of parameters beyond the terse schema descriptions.

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 (Lists) plus resource (the Claims & sources page), with an immediate clarification of what a claim and a source each are. The definition distinguishes itself from the mutation siblings (save_claim, retire_claim) by explicitly stating it 'Does not change anything.'

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

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

Gives concrete routing guidance: pass sourceId to see one source's full text 'before quoting it in save_claim,' and names the Related tools list. It explains what active vs retired claims mean in workflow terms, but stops short of an explicit statement of when to reach for this list versus other listing tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorld=false, so the safety profile is covered structurally. The description adds real behavioral context beyond that: the 50-item cap, the null-when-absent semantics of comparisonPages, and the effect of includeUntracked. It does not discuss pagination beyond the cap, but that is minor.

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 scope and shape, then the parameter behavior, then routing. No filler; the parenthetical defining aliases as 'other names AI answers count as naming them' resolves ambiguity in a single clause.

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

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

With an output schema present the description needn't enumerate return values, yet it usefully previews comparisonPages. Combined with annotations covering safety and a fully documented single parameter, 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, but the description adds semantic nuance the schema lacks: the schema says 'no longer tracked' while the description clarifies this means 'unstarred.' That extra interpretation is genuinely useful for a single-param tool.

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

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

States a specific verb and resource ('Lists the competitors this workspace tracks') and immediately bounds the scope with a row cap and the fields returned (ids, names, aliases, domains, comparisonPages). The explanation of comparisonPages per kind (vs, alternative, pricing) is precise enough that an agent knows exactly what it gets back.

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 conditional usage rule for the one parameter ('Pass includeUntracked to also see ones that were unstarred') and routes the agent via a 'Related' list of siblings (track_competitor, set_competitor_aliases, get_competitor_scorecard, draft_competitor_page). It stops short of explicitly stating when to prefer get_competitor_scorecard over this tool, so no exclusion guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial context they do not carry: the composition of lastSyncSummary (created, updated, unchanged, failed, complete, skipped reasons), what nextAction means, and per-reason remediation for skipped Drive files (shortcuts, unsupported types, >400 MB, trashed, unreadable folders). It also documents the cross-tool identity of connectionId.

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 routing in the first sentences, and every paragraph is information-dense. However, the middle paragraph detailing lastSyncSummary fields and per-reason remediation is heavy relative to the rest and partly overlaps the output schema, which an output schema already exists to describe.

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

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

For a zero-parameter, read-only list tool with an output schema, the description covers everything an agent needs: what is listed, what is not listed and where to go instead, the identifier vocabulary shared with sibling tools, and the correct path to actually create a connection. Nothing material is missing.

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

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

The tool takes zero parameters, so the baseline is 4 and the schema has nothing to explain. The description goes slightly beyond by defining connectionId as 'the provider name used by sync_connections, update_connection_settings, disconnect_connection and get_connect_link', which is genuinely useful interoperability context even though it is not a parameter of this call.

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

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

States a specific verb and resource ('Lists integrations') and enumerates the covered providers (Google, Search Console, GA4, Drive, analytics, CRM, email, Social publishing, website CMS) plus the returned status fields (health, last sync, failed jobs). It explicitly differentiates itself from list_channels and get_website_cms, so an agent can distinguish it from siblings 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?

Names alternatives and the conditions that select them: use list_channels to see which social accounts are connected, get_website_cms for the CMS. It also routes the connection workflow ('Connecting still happens in the Mark app — call get_connect_link for the in-app URL, then sync_connections'), giving explicit when-to-use and when-not-to-use guidance.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower. The description still adds real value: it explains that ideas never close on their own and only save_idea with archived:true closes one, and that it returns every tab's count. It also states 'Does not change anything,' which is a mild restatement of readOnlyHint but harmless.

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

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

Front-loads the purpose, then the filter semantics, then the returned fields, then the mutating-related note. Slightly dense with the long field enumeration, but every sentence earns its place and there is 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?

Given a 2-param read-only list tool with an output schema present, the description covers interpretation of filter values, the returned fields, archive semantics, and related tools. It does not need to explain return structure since an output schema exists; coverage is strong though not exhaustive.

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

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

Schema coverage is 100%, so both parameters (filter, pillarId) are fully documented in the schema itself. The description repeats the filter values without adding syntax or format details beyond what the schema provides, which is the baseline-for-100%-coverage case.

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 (Lists) and resource (content ideas) and immediately defines what an idea is ('things worth making content about, before or alongside the posts made for them'), which meaningfully disambiguates it from sibling post-listing tools like 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 filter enum is explained inline (active/no_posts/archived) and the description names related tools (save_idea, save_post). However, it doesn't explicitly state when to prefer this over search_posts or get_post, so routing between listing options is left partly implicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so safety, repeatability and external reach are covered. The description adds that results come from a third-party catalog and enumerates return fields, but the field list duplicates the output schema and no rate limits, latency, or empty-result behavior is disclosed.

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 purpose and value proposition before the boundary and related tools. The trailing 'Related:' list names three siblings of which only set_up_market is directly adjacent, which is mild noise.

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

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

For a simple read-only lookup with an output schema and full annotation coverage, nothing needed to call it correctly is missing: purpose, input semantics, no-side-effect guarantee, and adjacent tools are all present.

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

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

Schema description coverage is 100%, so 'place', 'language' and 'limit' are already documented with examples and bounds. The description only restates that search is by place name with optional language name, adding no syntax or format detail beyond the schema, which is the baseline case.

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 ('Searches the DataForSEO location and language catalog by place name'), plus what it returns. It also draws an explicit boundary ('Does not save a market'), which separates it from the setup/save siblings without needing their schemas.

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

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

Gives a clear motivating context ('so you do not have to guess codes') and one negative boundary ('Does not save a market'), plus a pointer to related tools. It stops short of stating when to prefer this over set_up_market or get_setup_status in concrete terms, so it is context without full routing rules.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the bar is lower, yet the description still adds real context: data is 'read live from Pinterest,' failure occurs when Pinterest is not connected or the list cannot load, and currentBoardId is null if unset. It does not cover pagination or freshness/latency behavior, 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 compact sentences, front-loaded with what is returned and followed by usage, failure modes, and related tools. 'Does not change anything' is mildly redundant with readOnlyHint/destructiveHint annotations, a small amount of non-earning text.

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 spelled out, yet the description still names fields and the null case; combined with failure conditions and the related-tool routing, an agent has everything needed to call this zero-arg, read-only tool correctly.

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

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

Zero input parameters, so the baseline is 4. The description's explanation of currentBoardId describes output semantics rather than inputs, which adds value but is technically beyond the parameter dimension.

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 ('Lists the connected Pinterest account's boards') with the returned fields enumerated, and explicitly disambiguates from siblings set_pinterest_board and list_channels. An agent can tell this apart from other list_* tools immediately.

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