RanklyBee

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

Annotations already declare a non-read-only, non-destructive, closed-world mutation, so the safety profile is covered. The description adds genuine behavioral context — starting the plan causes briefs to be written on their scheduled dates — but omits whether the action is reversible (e.g., via a pause), what happens if the plan is not yet reviewed, and idempotency.

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

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

A single front-loaded sentence that states the action and its consequence with no filler. Nothing in it could be trimmed without losing meaning.

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 three-parameter mutation with a real downstream effect (briefs get written), the description leaves the parameter sourcing and the returns unaddressed, and no output schema exists to offload that burden. Annotations cover safety only, so the definition is thin for the operation's complexity.

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

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

Schema description coverage is 0% and all three identifiers (projectId, siteId, planId) are required and undocumented in both schema and description. The description says nothing about how these are obtained or which is the authoritative scope, so it fails to compensate for the coverage gap.

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

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

Specific verb ('Start') plus resource ('a reviewed content plan') and an outcome ('its briefs are written on their scheduled dates'), which is clear enough to act on. It does not, however, name or explicitly distinguish itself from close siblings like generate_content_plan, decide_content_plan, or update_content_automation.

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 word 'reviewed' implies a prerequisite state (the plan must have been decided/approved first) and 'scheduled dates' implies the plan is already scheduled, so usage context is inferable. But there is no explicit when-to-use/when-not-to-use guidance and no mention of the alternative that produces the plan in the first place.

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 establish it is a non-read, non-destructive, open-world write. The description adds genuine context beyond them: activation depends on posts already being approved, publishing happens on a schedule, and user confirmation is required before invoking. It stops short of saying whether activation is reversible or what happens to unapproved posts.

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

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

Two short sentences, effect stated first and the safety instruction second. Nothing wasted or buried.

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

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

Covers the core action and the confirmation requirement, but for a mutation tool with no output schema it says nothing about the prerequisite campaign state, failure behavior, reversibility, or the undocumented confirmStackedChange flag. Adequate but with clear gaps.

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

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

Schema description coverage is 0% across four parameters, so the description carries the full burden and provides nothing: projectId, siteId, campaignId and especially confirmStackedChange are never explained. 'Approved posts' hints loosely at campaign state but does not map to any parameter.

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

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

States a specific verb+resource ('Start a campaign') and the outcome ('approved posts are published on schedule'), which distinguishes it from read/maintenance siblings. It does not explicitly separate itself from resume_distribution_campaign or activate_content_plan, which an agent could plausibly confuse with it.

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

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

'Confirm with the user first' gives one real precondition, but there is no guidance on when to prefer this over resume_distribution_campaign or pause_distribution_campaign, nor what state the campaign must already be in. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds semantic context about what is being persisted (an AI-answer brand as a competitor), but says nothing about duplicate handling, validation, idempotency, or what happens on conflict — gaps that matter for a create operation.

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

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

One front-loaded sentence with no filler or redundancy. It is efficient, though for a 4-parameter create tool with no schema descriptions it is arguably too brief rather than ideally sized.

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

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

A mutation tool with no output schema, 0% parameter documentation, and only minimal annotations; the description does not explain how projectId/siteId relate, what happens on duplicate brands, or what is returned. It is well short of sufficient for an agent 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?

All 4 parameters have 0% schema description coverage, so the description must carry the burden and it does not. It only loosely implies that the brand corresponds to 'name' and the destination to the site profile; required inputs projectId, siteId, and domain format/meaning are unexplained.

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 (save) and resource (competitor brand) and adds domain context — a brand observed in AI answers is recorded into the site profile. This is more informative than the bare name/title, but it never contrasts itself with siblings like exclude_ai_visibility_brand or get_ai_visibility_competitors.

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

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

The phrase 'a brand seen in AI answers' implies the scenario in which this tool applies, giving implied usage. However it provides no explicit when-to-use guidance, no prerequisites, and does not distinguish itself from related siblings such as exclude_ai_visibility_brand or restore_ai_visibility_brand.

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

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

Annotations only declare it is not read-only and not destructive, so the description carries most of the burden. It usefully discloses partial-success semantics ('returns the keywords that were skipped and why'), but says nothing about permissions, the 10-item cap being enforced, or duplicate/write-failure behavior.

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

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

Two tight sentences, front-loaded with the action and its effect, followed by the return behavior. Nothing is wasted; only the omission of the key term mapping ('keywords' vs the schema's 'phrases') hurts.

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

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

For a write tool with no annotations covering specifics, no output schema, and 0% parameter coverage, the description is thin. It never mentions the 10-phrase limit, the required project/site scoping, or what a successful add returns, leaving meaningful gaps for an agent to fill by guesswork.

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

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

Schema description coverage is 0% across 4 parameters, so the description must compensate and largely does not. It clarifies only scheduledDate ('optionally on a given date') and leaves projectId, siteId, and especially the phrases array (max 10 items, which it calls 'keywords' without connecting the terms) undocumented beyond the schema types.

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?

Clear verb+resource ('add keywords') plus the crucial qualifier that they are added 'as article briefs' to the content plan, which tells the agent what actually gets created. It does not, however, differentiate itself from near-identical siblings like import_article_keywords or add_outreach_keywords, leaving the agent to guess which adder is correct.

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

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

The only usage hint is the optional date, implying scheduling context. There is no statement of when to use this versus import_article_keywords (bulk import) or add_outreach_keywords, which is exactly the ambiguity an agent faces with this sibling set.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds only the vague notion of 'start tracking' and says nothing about duplicates, required permissions, or what side effects creating a tracked backlink has. With annotations carrying the burden, a 2 reflects minimal added 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?

A single sentence, front-loaded with the action and immediately clarifying the two URL parameters. No filler, though it is arguably too terse for a 15-parameter tool.

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

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

For a 15-param, 5-required mutation tool with no output schema and 0% schema coverage, the description is far too thin. An agent cannot know the semantics of most required fields or the return behavior from the description.

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

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

Schema description coverage is 0% across 15 parameters, so the schema explains nothing. The description clarifies only 2 of the 15 (sourceUrl, targetUrl) and is silent on required params like projectId, siteId, source, and the pricing/category/rel fields. It fails to compensate for the coverage gap.

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

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

A clear verb+resource ('Start tracking a backlink') with an added gloss clarifying what sourceUrl and targetUrl mean in the link relationship. It reads distinct from check_backlink (verification) and list_backlinks (enumeration), but it never explicitly names or rules out those siblings, so it stops short of 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?

No when-to-use guidance at all. Given the dense sibling set (check_backlink, create_backlink_submission, close_backlink, update_backlink_task), the description gives the agent no criteria for choosing this tool over the 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 this is a non-read-only, non-destructive, non-open-world write, so safety is covered. The description adds nothing beyond that: it does not say whether duplicate URLs are rejected, what happens on conflict, what permissions are needed, or what is returned. For a creation tool it leaves the behavioral profile largely unexplained.

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

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

It is a single front-loaded sentence with the verb first and no filler. It is efficient, though arguably too terse for a tool with four required parameters and zero schema documentation.

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 0% schema coverage, no output schema, and only sparse annotations, the description is the sole source of detail — and it provides almost none. An agent would know what the tool does in general but not how to populate projectId/siteId or what behavior to expect on success or failure.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It only loosely gestures at 'url' and 'title' ('a page of the website', 'articles should link to') and never mentions projectId or siteId at all, leaving two of four required identifiers completely undocumented.

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

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

The description uses a clear verb ('Add') and describes the resource conceptually ('a page of the website that articles should link to'), which is distinguishable from the sibling remove_internal_link_target and list_internal_link_targets. However, it never uses the term 'internal link target' itself and does not explicitly contrast with those siblings, so the differentiation is implicit rather than stated.

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

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

There is no when-to-use guidance, no prerequisites (e.g., that a projectId/siteId must already exist), and no mention of alternatives such as list_internal_link_targets for inspecting existing targets or remove_internal_link_target for deletion. Usage must be inferred entirely from the tool name.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: it does not say whether duplicate keywords are merged, whether the operation is idempotent, what project/site scope is required, or anything about the result of a bulk add.

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

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

A single front-loaded sentence with no filler; the problem is under-specification rather than verbosity. It reads cleanly but is arguably too terse for a 3-parameter mutation tool.

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

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

For a three-parameter write tool with zero schema descriptions and no output schema, the description omits almost everything an agent needs: project/site targeting context, dedup behavior, and confirmation of effect. The per-item constraints (maxItems 100, maxLength 200) exist only in the schema and are never surfaced.

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

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

Schema description coverage is 0% across three required parameters, so the description must carry the burden and largely fails. It implies the phrases array ('keywords') but leaves projectId and siteId completely unexplained, forcing the agent to guess at the scope of the write.

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

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

The description gives a specific verb plus resource (add keywords) and scopes it to link prospecting, so the agent can tell it targets outreach/prospecting keywords rather than article or lead keywords. It does not name the sibling it differs from (add_article_keywords, create_lead_keyword), 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?

There is no when-to-use guidance and no alternatives cited, despite siblings list_outreach_keywords and remove_outreach_keyword existing. The agent must infer that this is the create-side of the outreach keyword lifecycle without any stated condition or prerequisite.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so safety and open-world behavior are covered structurally. The description adds one genuine behavioral fact beyond that – the prospect is scored on creation – but says nothing about duplicate handling, scoring criteria, or auth/permission 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?

A single tight sentence with the core action front-loaded and no filler. It is efficient, though extremely sparse for the amount of behavior it needs to convey.

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

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

For a mutation tool with three mandatory, fully undocumented parameters and no output schema, the description should explain the two ID parameters and the result of scoring. It leaves the agent guessing about scope and outcome, which is inadequate for this complexity.

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

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

Schema description coverage is 0% for all three required parameters. The description only obliquely implies a URL ('page', 'by URL' in the title) and gives no meaning for projectId or siteId, so half the parameter surface is undocumented anywhere.

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 pairs a specific verb ('Add') with a specific resource ('link prospect') and adds an extra action ('score it'), so it is clearly not a list/read tool. However, it never differentiates itself from adjacent siblings such as start_prospect_discovery or reject_prospect, so an agent must infer the boundary.

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

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

There is no guidance on when to use this versus the automatic discovery flow (start_prospect_discovery) or unblock_prospect_domain. The agent gets no conditions, prerequisites, or exclusions, only a bare imperative.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds valuable async behavior: it runs in the background and requires polling get_site_profile. It does not explain idempotency or potential side effects of rebuild, but it goes beyond annotations.

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

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

Two tightly written sentences: first the action, then the follow-up. No filler; front-loaded.

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

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

Covers the essential operational flow (trigger, background, poll for result) and references the output tool. However, for a mutation with 4 parameters and no schema descriptions, it fails to explain what the parameters do or what 'rebuild' entails, leaving important gaps.

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

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

Schema description coverage is 0% for all four parameters. The description does not mention any parameter, including the required idempotencyKey or the optional reviewFoundation, leaving their meaning entirely undocumented.

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

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

States a specific action: re-crawl the website and rebuild its profile. It clearly distinguishes from the read-only sibling get_site_profile, which it names explicitly.

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

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

Explains the background execution and tells the agent to poll get_site_profile for results. It does not provide explicit when-not-to-use guidance or alternatives for triggering re-analysis, but the context is clear.

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

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

Annotations already declare that this is a non-read-only, open-world, non-destructive mutation. The description adds a useful confirmation requirement beyond the annotations, but does not disclose what is mutated, whether the change is reversible, or what permissions may be 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 with no wasted language: the purpose is front-loaded and the confirmation requirement follows. It is appropriately terse, though the brevity contributes to the definition's overall gaps.

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 parameterized mutation tool with zero schema descriptions and no output schema, the description is too thin. It omits parameter meaning, sibling disambiguation, and what actually happens after the improvement is applied.

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

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

Schema description coverage is 0% for three required parameters (projectId, siteId, improvementId), and the description provides no mapping or explanation of any of them. It fails to compensate for the complete absence of parameter documentation in 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 clear verb ('Apply') and resource ('approved improvement to its article'), so the agent knows this performs an application action rather than generating, deciding, or updating an improvement. However, it does not differentiate itself from closely named siblings such as update_article_improvement or submit_article_improvement.

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

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

The phrase 'approved improvement' implies a precondition and 'Confirm with the user first' gives a procedural constraint, but there is no explicit when-to-use/when-not-to-use guidance and no named alternative among the many article-improvement 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=false, destructiveHint=false, openWorldHint=true, so the agent knows this is a non-destructive external write. The description adds the meaningful confirmation requirement ('Show the user each post first') and the social-publishing target, but says nothing about reversibility, what approval triggers, or whether it can be undone.

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

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

Two short sentences with the core action front-loaded and the safety instruction second. Nothing is padded or redundant.

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

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

Annotations cover the safety profile and no output schema is required, so the main gap is the undocumented parameters and the absence of any statement about what approval actually does (schedule? immediate publish?). Adequate but thin for a state-changing batch operation.

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

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

Schema description coverage is 0% for three required parameters, so the description carries the full burden and largely fails it. 'posts' loosely hints at postIds, but projectId and siteId are never explained, nor is the 200-item cap or that the array is a batch operation.

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

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

States a specific verb (Approve) and resource (distribution posts) plus the consequence (publishing to the user's social accounts), which is enough to tell it apart from reject_distribution_posts and edit_distribution_post by verb alone. It does not explicitly name a sibling, so it falls short of a 5.

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

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

The line 'Show the user each post first' is a genuine usage rule about presentation before invocation, but there is no guidance on when to approve versus reject or edit, nor any precondition about post state. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the safety profile is partly covered. However, the description adds nothing about the side effect it implies — whether extracted atoms are persisted, replace prior atoms, or are idempotent on repeat calls — which is the key behavioral question for a non-read-only 'atomize' operation.

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

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

A single compact sentence with the action front-loaded and no filler. It is appropriately sized, though its brevity comes at the cost of missing detail rather than being tight-but-complete.

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

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

For a non-read-only tool with three undocumented parameters and no output schema, the description omits what an agent needs: parameter roles, whether atoms are stored/replaced, and any prerequisite linking pageUrl to a known site. It is too thin for the tool's complexity.

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

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

All three required parameters (projectId, siteId, pageUrl) have 0% schema description coverage, so the burden falls on the description, which says nothing about them. The phrase 'Read a page' weakly implies pageUrl, but the relationship and expected formats of projectId/siteId are left unspecified.

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 verb phrase 'Read a page and extract talking points for social posts' names a concrete action and resource, and the output purpose (social posts) is explicit. It is clear enough to separate from retrieval siblings like get_distribution_page_atoms or list_distribution_pages, but it never names a sibling to disambiguate.

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

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

There is no guidance on when to call this versus get_distribution_page_atoms, list_distribution_pages, or regenerate_distribution_post, nor on prerequisites (e.g., whether the page must already exist in the distribution set). The agent must infer the workflow position entirely.

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 write (readOnlyHint=false) and non-destructive behavior. The description adds genuinely useful context beyond that — the per-call cap of 100 and that the operation consumes the plan's prompt quota. It stops short of describing partial-failure, quota-exceeded, or duplicate handling.

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

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

Two short sentences with zero filler, and the batch capability and quota impact are front-loaded.

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

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

For a batch mutation with nested per-monitor objects and a quota side effect, and no output schema to lean on, the description omits what happens on limit overflow, whether the batch is atomic or partial, and any deduplication rules. Annotations cover safety only, so the description under-delivers for this complexity.

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

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

Schema description coverage is 0% across 3 required parameters, and the nested 'monitors' objects carry 8 fields (engines, question, keywords, brandAliases, frequency, etc.) with no documentation. The description only echoes the 100-item cap already present as maxItems, leaving projectId/siteId and monitor field intent unexplained.

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

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

States a specific verb+resource ('Add ... prompts') with a clear batch scope ('up to 100 at once'), which implicitly distinguishes it from the singular sibling create_ai_visibility_prompt. It doesn't name the alternative explicitly, 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?

No when-to-use guidance beyond the implicit batch framing, and no named alternatives such as create_ai_visibility_prompt or suggest_ai_visibility_prompts. The quota note is a constraint, not usage routing.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the bar is lower. The description adds valuable specificity by naming what is destroyed: unpublished posts in the connected social scheduler. It still omits irreversibility, permission requirements, and the effect on already-published posts, but the destruction target is a meaningful addition 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 description is a single front-loaded sentence with no filler or repetition. It states the action and its key side effect efficiently, with every clause earning 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 destructive external mutation with three undocumented required IDs and no output schema, the description covers what happens but not parameter semantics, prerequisites, or alternatives. The annotations cover the safety profile, but the description does not compensate for the complete lack of schema parameter documentation.

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

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

Schema description coverage is 0%, and all three required parameters (projectId, siteId, campaignId) lack any schema description. The description adds no meaning, format, or source information for these identifiers, leaving the agent with only parameter names and string types.

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 (cancel) and resource (campaign), plus the concrete effect of removing unpublished posts from the connected social scheduler. This implicitly distinguishes it from pause/resume/activate siblings, but does not explicitly name any alternative, so sibling differentiation is not fully explicit.

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

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

The description gives no when-to-use or when-not-to-use guidance. It does not mention pause_distribution_campaign, resume_distribution_campaign, or update_distribution_campaign as alternatives, nor does it state prerequisites or confirmation requirements for cancellation.

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

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

The annotations already declare readOnlyHint=false, openWorldHint=true, and destructiveHint=false. The description adds that it fetches an external linking page and records liveness, which clarifies the write side effect. It still omits permissions, rate limits, and exactly what status is recorded.

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

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

The description is a single front-loaded sentence with no wasted words. It efficiently states the fetch and record behavior.

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

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

For a tool requiring four identifiers including an idempotency key and involving an external fetch plus recorded status, the description is too thin. With no output schema and no parameter descriptions, an agent still lacks important context about inputs and side effects.

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

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

Schema description coverage is 0% and the description mentions no parameters at all. It does not explain projectId, siteId, backlinkId, or especially idempotencyKey, leaving the four required parameters completely semantically undocumented.

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: fetch the linking page and record whether the backlink is still live. This makes the tool's core purpose clear. However, it does not explicitly differentiate from close siblings such as check_site_backlinks or get_backlink_inventory_status.

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

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

No when-to-use guidance or prerequisites are given. The description does not explain when to choose this single-backlink check versus bulk backlink checks, inventory status, or other backlink 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=false, destructiveHint=false and openWorldHint=true, so the agent knows this is a non-destructive but mutating external-world action. The word 'Queue' usefully signals asynchronous enqueueing rather than immediate results, but the description says nothing about rate limits, whether concurrent runs conflict, or how the queued job's outcome is later retrieved.

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 tight sentence with the action and scope front-loaded; every word 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?

For a mutating, open-world tool with three fully undocumented required parameters and no output schema, the description is far too thin. It omits what the queue actually does, how to observe completion (e.g. get_backlinks_overview or get_backlink_inventory_status), and why an idempotency prefix is mandatory.

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

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

Schema description coverage is 0% and all three required parameters (projectId, siteId, idempotencyPrefix) are undocumented. The description implies site/project scoping through 'of a website' but never explains any parameter, and the required idempotencyPrefix with its 8-160 character constraint is completely unaddressed.

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 (queue/check), resource (backlinks), and scope (every tracked backlink of a website). The scope word 'every' implicitly separates it from the singular sibling check_backlink, but no sibling is named explicitly, 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as check_backlink (single) or list_backlinks/get_backlinks_overview for reading existing data. The only hint is the verb 'queue', which implies initiating work rather than reading results, but this must be 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 readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds only 'with a reason,' which is already enforced by the schema; it does not disclose whether closing is reversible, what happens to historical data, 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?

The single sentence is front-loaded, has no waste, and states the core action and required input immediately. It is efficient, though its extreme brevity leaves no room for necessary supporting context.

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

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

For a mutation tool with four required parameters and no output schema, the description is too sparse. It omits consequences of closing, prerequisites, and parameter explanations, and adds little beyond the title and annotations.

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

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

Schema description coverage is 0%, so the description must compensate for all four parameters. It hints that a reason is required, matching one parameter, but provides no meaning for projectId, siteId, or backlinkId, leaving three parameters entirely undocumented.

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 ('Close') and resource ('tracked backlink') with a required input ('with a reason'). It is distinguishable from siblings like add_backlink or update_backlink_task, though it does not explicitly name an alternative or differentiate further.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as update_backlink_task. The implied context (stop tracking a backlink) is tautological with the purpose statement, offering no real decision support.

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, openWorldHint=false, so the agent already knows this writes without being destructive. The description adds 'record the result,' clarifying that it persists output rather than just returning a comparison, but it does not say what is stored, whether prior measurements are overwritten, or what the measurement window is.

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

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

A single front-loaded sentence with no filler or repetition. It is efficient, though its brevity borders on under-specification given the gaps elsewhere rather than reflecting deliberate tightness.

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

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

For a write tool with no output schema and three fully undocumented parameters, the agent lacks key information: what metric is compared, over what window, and what the recorded result consists of. The annotations cover the safety profile, but the description does not compensate for the missing parameter and outcome detail.

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

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

Schema description coverage is 0% across three required parameters (projectId, siteId, improvementId). The description only obliquely ties to improvementId via 'applied improvement' and says nothing about projectId or siteId or their relationships, leaving the schema undocumented in both structured and prose form.

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 (search performance before/after an applied improvement) plus the side effect of recording the result, which distinguishes it from siblings like generate_article_improvement or decide_article_improvement. However, it does not explicitly name those siblings or contrast the measurement role against them.

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

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

The phrase 'an applied improvement' implies a precondition (the improvement must already be applied, presumably via apply_article_improvement), which gives implied usage context. But there is no explicit when-to-use statement and no alternatives named, so an agent must infer the sequencing.

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

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

Annotations already declare the write operation (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the safety profile is covered. The description adds one genuinely useful trait beyond the annotations: the call consumes a quota ('Counts against the plan's prompt limit'). It omits failure behavior, idempotency, and permission requirements, so it is helpful but not rich.

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

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

Two short sentences with the action front-loaded and no filler; the quota constraint is a useful trailing detail. It is appropriately sized, though the brevity is partly what leaves the complex parameter structure undocumented.

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 create tool built around a required nested object with 0% schema description coverage and no output schema, the description is far too thin. An agent has no guidance on how to populate monitor.question, engines, frequency, keywords, or brandAliases, nor on what a successful creation returns.

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

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

Schema description coverage is 0% and the tool requires a complex nested 'monitor' object with five required sub-fields (question, keywords, brandAliases, engines, frequency) plus projectId and siteId. The description adds essentially nothing about these — 'across AI engines' only faintly gestures at the engines field. This is a large documentation gap the description fails to close.

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

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

The description states a specific verb+resource ('Add a prompt to track') and names the domain ('across AI engines'), which is enough to distinguish a create from list/update/delete siblings. It does not, however, differentiate from the close sibling bulk_create_ai_visibility_prompts or suggest_ai_visibility_prompts, so an agent still has to infer which create variant applies.

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 offers no when-to-use, when-not-to-use, or alternative guidance. The mention of a plan prompt limit hints at a cost constraint but never tells the agent to check get_plan_usage first or to prefer bulk_create_ai_visibility_prompts for multiple prompts, leaving routing entirely 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 only declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false; they do not explain creation semantics. The description says nothing about name uniqueness, what happens on a duplicate, required scopes, or the response shape for this mutation. For a create tool it leaves the behavioral picture mostly blank.

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

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

A single short, front-loaded sentence with no wasted words. It is efficient but borders on under-specification, since the brevity leaves key information absent rather than merely compact.

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 three-required-parameter mutation tool with no output schema and no annotation richness, the description omits ownership/scope context (why projectId and siteId are both needed) and creation behavior. It is inadequate relative to the tool's complexity.

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

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

All three parameters (projectId, siteId, name) have 0% schema description coverage, so the schema provides no meaning, and the description does not describe a single parameter or its constraints. The description entirely fails to compensate for the coverage gap.

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

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

States a specific verb (create) and resource (topic) and clarifies the topic's purpose as a grouping container for prompts, which hints at its distinct role versus create_ai_visibility_prompt. It does not, however, explicitly name a sibling or state how a topic differs from a prompt beyond the grouping phrase.

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

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

No when-to-use or when-not-to-use guidance is given, and no alternatives are mentioned despite siblings like bulk_create_ai_visibility_prompts, rename_ai_visibility_topic, or create_ai_visibility_prompt. The agent must infer context entirely from the name.

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

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

Annotations only cover the generic safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false). The description adds genuinely new behavioral facts: the job is idempotent, it is created in a waiting_human state, and it deliberately does NOT trigger the third-party final submit — an important side-effect boundary. No auth or rate-limit detail, 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?

Two tight sentences: the precondition and action are front-loaded, and the second sentence exists only to draw the side-effect boundary. No filler or restated boilerplate.

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

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

For a mutation tool with no output schema and zero schema-description coverage, the description covers state and the critical "does not submit" caveat, but leaves the four required identifiers unexplained and does not say whether a preflight call is a prerequisite. Adequate, with real gaps an agent would hit.

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

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

Schema description coverage is 0% and all four parameters (projectId, siteId, sourceId, idempotencyKey) are required and completely undocumented. The description's mention of an "idempotent" job hints at idempotencyKey's role, but it explains nothing about siteId, sourceId, projectId, or the 8-120 char key format, so it fails to compensate for the coverage gap.

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

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

The description gives a specific verb+resource (create a submission job) and pins the resulting state (waiting_human), which cleanly separates it from siblings like get_backlink_submission and record_backlink_submission_outcome. It stops short of naming an alternative sibling, so it lands at a clear-but-undifferentiated 4.

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?

"After user review and approval" establishes a real precondition for calling this tool, which is more than nothing. However, it never names preflight_backlink_submission or record_backlink_submission_outcome as the surrounding steps in the workflow, so the agent must infer where this sits in the sequence.

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

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

Annotations already establish that this is a non-read-only, non-destructive, closed-world write. The description adds nothing beyond that: no mention of deduplication against existing contacts, permission/ownership requirements, or what happens to the seven required identifiers.

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 words is not conciseness but under-specification; it is front-loaded but has no substance to front-load. Nothing about the 12-parameter surface is conveyed.

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

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

For a tool with 12 parameters, 7 of them required, 2 enums, no parameter descriptions, and no output schema, a four-word description is wholly inadequate. An agent has no basis for constructing a valid call.

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

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

Schema description coverage is 0% across 12 parameters, so the burden falls entirely on the description, which conveys zero parameter meaning. Critical details such as the 'source' default of 'manual' or the distinction between sourceUrl/sourceProvider/sourceReference are left completely undocumented.

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

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

The description gives a clear verb+resource ('Add a contact'), and 'by hand' hints at manual entry, which distinguishes it loosely from find_prospect_contact/select_prospect_contact. But it says nothing about what a 'contact' is scoped to here (project/site/prospect), so it does not cleanly separate itself from add_prospect or verify_contact.

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

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

There is no guidance on when to use this versus find_prospect_contact, select_prospect_contact, add_prospect, or verify_contact, all of which live in the same contact/outreach area. No prerequisites or exclusions are stated.

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

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

Annotations already declare the safety profile (not read-only, not destructive, closed-world). The description adds real value with 'draft' — the campaign is not live until activated — but omits the critical behavioral distinction that 'auto_publish' mode publishes without review, which an agent needs before calling.

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

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

A single front-loaded sentence with no filler. Efficient, though the brevity is arguably over-compression given the tool's complexity rather than a model of crispness.

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

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

For an 11-parameter, 10-required tool with a nested object and no output schema, the description is far too thin. It should at minimum explain the mode enum semantics, the cadence shape, and account targeting.

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

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

Schema description coverage is 0% across 11 parameters, including a nested cadence object, so the description carries the full burden and does not meet it. It vaguely gestures at pageUrl ('a page'), scheduling ('scheduled'), and mode ('draft') but explains none of accountIds, cadence fields, maxPostsPerAccount, or autoPublishAccountIds.

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 (create), resource (distribution campaign), and outcome (a draft that turns a page into scheduled social posts). The word 'draft' cleanly separates it from activate/pause/cancel siblings, though no sibling is named explicitly.

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

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

No when-to-use guidance, no prerequisites, and no alternatives. The agent can infer it precedes activate_distribution_campaign from the word 'draft', but nothing states that workflow or when to prefer this over atomize_distribution_page.

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

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

Annotations already establish that this is a non-read-only, non-destructive, closed-world write. The description adds only the side effect (a channel notification), but says nothing about required permissions, whether rules are active on creation, or how conditional fields like webhookUrl or recipientEmail relate to the chosen channel.

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

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

A single front-loaded sentence with no filler or repetition. It is efficient, though the brevity comes at the cost of the missing detail noted in other dimensions.

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

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

For a tool with a nested rule object, two enums, conditional field requirements, three required top-level params, and no output schema, the description is far too thin. It gives no guidance on valid triggers/channels or on the shape of the rule payload.

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

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

Schema description coverage is 0% and the description documents none of the parameters. It never mentions channel, trigger, targetStage, webhookUrl, or recipientEmail, nor the conditional relationship (webhookUrl needed for webhook, recipientEmail for email) that an agent must satisfy to call this correctly.

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

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

The description gives a specific verb and resource ("Create a rule") plus the effect ("notifies a channel when matching leads arrive"), so an agent knows this is a write tool that wires up lead alerts. It does not, however, distinguish itself from close siblings like list_lead_alert_rules, delete_lead_alert_rule, or set_lead_alert_rule_status, all of which operate on the same resource.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the alternative sibling tools for the same resource. The agent must infer from the name alone that this creates rather than lists, deletes, or toggles a rule.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write/non-destructive profile is covered. The description adds the useful context that created profiles drive lead scoring, but says nothing about permissions, limits, or what happens on conflicts with existing profiles.

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

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

One short, front-loaded sentence with no filler waste. It is efficient, though the brevity borders on under-specification for the parameter complexity involved.

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 create tool with three required parameters, a nested seven-field object, no output schema, and zero schema descriptions, the description leaves the agent without enough to populate a meaningful ICP or understand the required ids. More detail is clearly needed.

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

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

Schema description coverage is 0% and the description documents no parameters at all. The nested 'icp' object contains seven subfields (name, roles, exclusions, industries, painPoints, description, intentPhrases) plus projectId and siteId, none of which are explained — a serious gap for a nested-object mutation.

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

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

The description gives a specific verb and resource ('Add a customer profile') and adds the functional context that profiles are what 'leads are scored against,' which sharpens intent beyond the name. It does not distinguish itself from siblings like update_lead_icp or delete_lead_icp, so it falls short of a 5.

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

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

There is no guidance on when to create an ICP versus updating one, no mention of prerequisites, and no reference to alternatives in the large sibling set. The agent must infer usage entirely.

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

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

Annotations declare this is a non-destructive write (readOnlyHint=false, destructiveHint=false), so the safety profile is covered. The description adds nothing beyond 'add' — no duplicate-handling behavior, no per-project limits, and no mention of what happens when the keyword already exists.

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

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

One efficient, front-loaded sentence with no filler. It is appropriately sized, though its brevity comes partly from under-specification rather than disciplined editing.

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

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

A mutation tool with a nested object, 0% schema description coverage, and no output schema; the description covers only a fraction of what an agent needs. Key creation semantics — required scoping IDs, keyword type taxonomy, and negative keyword support — are absent.

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

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

Schema description coverage is 0% and the payload is a nested object with five subfields, so the description carries the burden. It mentions only 'search phrases' (queries) and 'platforms', leaving name, the type enum (buyer_intent/tool/competitor/topic/brand), negativeKeywords, and the required projectId/siteId scoping unexplained.

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 ('Add a keyword to monitor') and hints at the payload shape. However, it does not differentiate from closely named siblings like add_article_keywords and add_outreach_keywords, so an agent must infer which keyword store this targets.

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

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

The description gives no when-to-use context, no prerequisites, and does not name alternatives such as add_article_keywords or add_outreach_keywords. The 'to monitor' phrase implies lead-monitoring scope but never states it 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 a non-readOnly, non-destructive write, and the description usefully adds that no email is actually dispatched ('Nothing is sent'), which is real behavioral context. However it says nothing about whether the draft persists, whether it overwrites an existing draft, or what permissions are required.

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 action front-loaded and the side-effect caveat immediately after. No filler, though it is terse enough that it under-serves the 7-parameter signature.

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

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

For a 7-param tool with 0% schema coverage and no output schema, the description is thin. It covers the core outcome (draft created, nothing sent), but an agent still can't tell how to disambiguate this from prepare_outreach_draft or how generationMode interacts with the template.

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

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

Schema description coverage is 0% across 7 parameters, so the description must carry the load. It names only 'template' and 'sender' (templateId, senderIdentityId) and ignores projectId, siteId, prospectId, contactId entirely. Worse, it says the email comes 'from a template' while generationMode defaults to 'ai', leaving the key mode parameter unexplained and its default counterintuitive.

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: writing a first outreach email to a prospect's contact, composed from a template and sender. It clearly differentiates itself from send/regenerate siblings via 'Nothing is sent', but does not distinguish itself from the similarly named prepare_outreach_draft or update_outreach_draft.

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

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

No explicit when-to-use or when-not-to-use guidance. The presence of prepare_outreach_draft, get_outreach_draft_options, and create_outreach_template as siblings makes the workflow ordering ambiguous, and the description offers nothing to disambiguate which step to call first.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered, but the description adds nothing beyond that. It does not say the template is bound to a project/site, whether duplicate names are permitted, or how placeholder tokens in subjectTemplate/bodyTemplate are interpreted.

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

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

It is a single short sentence, but the brevity is under-specification rather than efficiency. There is no wasted wording, but the sentence carries no useful payload.

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

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

For a mutating, 6-parameter tool with a nested object, five required fields, zero schema descriptions, and no output schema, the description is wholly inadequate. An agent cannot determine required inputs, template placeholder semantics, or scoping from this text.

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

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

Schema description coverage is 0% across 6 parameters, so the description carries the full explanatory burden and provides none of it. Nothing explains name constraints, subject/body template syntax, or the nested fallbackValues object — all of which an agent must understand to call this correctly.

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 says 'Create an email template,' which is essentially a restatement of the tool name and title 'Create an outreach template.' It identifies a verb and resource but adds no distinguishing detail (placeholders, subject/body structure, project/site scoping) and does nothing to separate it from siblings like create_outreach_draft or update_outreach_template.

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

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

There is no guidance on when to create a template versus drafting a one-off reach-out (create_outreach_draft) or modifying an existing template (update_outreach_template). Nothing indicates prerequisites, required project/site context, or reuse intent.

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

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

Annotations already declare it is a non-read-only, non-destructive write. The description adds one genuinely useful behavioral fact the annotations cannot convey: imageStorageKey must be passed as null (i.e., no image at creation time). It says nothing about permissions, side effects, or how to attach an image later.

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, action first, with the parameter caveat trailing. No filler, no redundancy.

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

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

For a write tool with a nested required payload, no output schema, and 0% schema description coverage, the description should at least sketch what the product fields are or what comes back on success. It covers one quirky parameter and omits the rest, so an agent cannot confidently populate the required fields object.

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

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

Schema description coverage is 0% across 4 parameters, including a nested fields object with five required sub-properties (title, url, description, price, currency) that are completely undocumented. The description clarifies only imageStorageKey, leaving the bulk of the parameter semantics unexplained and not compensating for the coverage gap.

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

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

Specific verb+resource: 'Add a product to the catalog' clearly identifies a creation operation on the product resource. It does not, however, differentiate from close siblings like update_product or set_product_status, leaving the agent to rely on the name alone.

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

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

No when-to-use guidance, no prerequisites, and no routing to alternatives such as update_product for existing products. The only usage-like instruction concerns a single parameter value, not the choice of tool.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the agent knows this is a bounded mutation. The description contributes the behavioral precondition that the article must be awaiting approval, but says nothing about permissions required, whether a reason is expected for rejection, or what the decision changes downstream.

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

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

A single short sentence with the action front-loaded and no filler. It is efficient, though its brevity reflects under-specification rather than disciplined editing.

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

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

For a five-parameter mutation tool with no output schema and zero schema descriptions, the description leaves too much unsaid: it does not explain the required identifiers, the effect of each decision value, or whether reason is mandatory for rejections. Only the state precondition is conveyed.

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

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

Schema description coverage is 0% across five parameters, so the description carries the full documentation burden and does not meet it. 'Approve or reject' loosely maps to the decision enum, but projectId, siteId, assetId, and reason receive no explanation of format, source, or when reason is required.

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

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

The description gives a specific verb pair (approve/reject) and resource (article), plus a state qualifier ('waiting for approval') that separates it from submit_article_for_review and publish_article. It does not name the closely-named siblings decide_content_brief, decide_content_plan, or decide_article_improvement, so an agent must infer the distinction from the resource noun alone.

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

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

There is no explicit when-to-use guidance, no named alternative, and no statement of what to do if the article is not in the pending state. The 'waiting for approval' clause weakly implies the precondition but the description never instructs the agent on routing between this tool and the other decide_* or publish_article 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 establish the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description only needed to add mutation-specific context. It adds none: nothing about whether the decision is reversible, whether approving triggers the improvement to be applied, what happens to the reason field, or any permission requirements. For a write/decision tool this is a real gap.

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

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

A single front-loaded sentence with zero padding or redundancy. It is efficient, though its brevity is a symptom of under-specification rather than disciplined concision.

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

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

A 5-parameter mutation tool with no output schema, no parameter descriptions, and no meaningful annotation beyond safety flags. The description leaves the agent without the field semantics, side effects, or state transitions it needs to invoke this confidently, especially versus its many look-alike 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 description coverage is 0% across 5 parameters, so the description carries the full burden of explaining projectId, siteId, improvementId, decision, and reason. It mentions none of them, including whether reason is optional or what the approved/rejected enum implies operationally. Only the schema's own enum and required list give the agent anything to work with.

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 pair (approve/reject) and the resource (an improvement), so the action is unambiguous. However, it never differentiates itself from the dense sibling set of near-identical decision tools (decide_article, decide_content_brief, decide_content_plan) or from dismiss_article_improvement and apply_article_improvement, which also act on improvements. Clear but not sibling-distinguishing.

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

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

The only usage signal is the state condition 'waiting for approval', which is close to restating the tool's purpose rather than guidance. There is no indication of when to choose this over dismiss_article_improvement, apply_article_improvement, or the other decide_* tools, and no prerequisites or ordering information. Essentially no routing guidance despite a crowded sibling namespace.

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

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

Annotations already declare a non-read-only, non-destructive mutation, and the description adds nothing beyond that: it does not say whether a decision is reversible, whether approval triggers downstream generation, whether a rejection reason is required, or what side effects follow. For a state-changing tool, the description leaves the important behavioral consequences undisclosed.

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

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

A single front-loaded sentence with no filler, which is structurally clean. It is efficient, though arguably too terse for a six-parameter mutation.

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 six-parameter write tool with 0% parameter documentation, no output schema, and only terse annotations, one sentence is not sufficient. An agent gets no information about identifier semantics, the reason field, or the consequences of each decision.

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

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

Schema description coverage is 0% across six parameters (five required), so the description carries the full burden and fails it. 'Approve or reject' loosely implies the decision enum, but projectId, siteId, planId, briefId, and the optional reason are never explained, including the fact that reason exists at all.

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

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

States a specific verb pair (approve or reject) and a specific resource (one article brief in a content plan), which is enough to distinguish it from decide_content_plan and decide_article. It lacks explicit sibling differentiation, but the narrow scope is clear from the wording.

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

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

There is no guidance on when to use this tool versus decide_article, decide_article_improvement, or decide_content_plan, all of which sit in the same sibling cluster. The phrase 'in a content plan' implies context but leaves prerequisites and alternatives to inference.

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

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

Annotations already declare this is a non-read-only, non-destructive, closed-world write, so the safety profile is covered. The description adds essentially nothing beyond the title: it does not say what approval triggers downstream, whether rejection requires a reason, or whether the decision is reversible/idempotent.

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

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

A single front-loaded sentence with no filler, but it is largely a restatement of the title and therefore earns little of its space. It is concise to the point of under-specification rather than genuinely economical.

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

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

For a 5-parameter mutation tool with no output schema and 0% parameter documentation, the description is far too thin. It omits required inputs, the meaning of 'reason', and the consequences of the approve/reject decision, leaving the agent to guess at call semantics.

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

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

Schema description coverage is 0% across 5 parameters, so the description carries the full burden of explaining planId, projectId, siteId, reason, and decision. It only implicitly echoes the approve/reject enum values and says nothing about the required identifiers or the purpose of 'reason'.

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 verb pair (approve/reject) and resource (content plan), and the word 'whole' hints that this operates at the plan level rather than on individual items. It does not explicitly distinguish itself from close siblings like decide_content_brief, decide_article, or activate_content_plan, but the purpose is unambiguous.

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

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

There is no guidance on when to use this tool versus siblings such as activate_content_plan or decide_content_brief, and no prerequisites are stated (e.g., that a plan must first exist from generate_content_plan). The agent must infer all usage context.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is covered structurally. The description adds one genuinely useful behavioral fact beyond the annotations: the deletion is cascading, taking the prompt's run history with it. It still omits reversibility (no sibling restore/undelete exists for prompts), permission requirements, and return behavior.

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

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

A single front-loaded sentence with no filler or repetition; the destructive scope ('and its history') is stated immediately. It is terse rather than padded, though the terseness comes at the cost of guidance the agent needs.

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

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

For a destructive, irreversible-adjacent operation with three completely undocumented identifier parameters and no output schema, the description is thin. It should at minimum clarify that all three IDs are needed to identify the prompt and warn that history loss cannot be undone; the annotations alone do not tell the agent which identifiers to supply.

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

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

Schema description coverage is 0% for three required identifiers (projectId, siteId, monitorId), and the description supplies no parameter information whatsoever — it only implies a single prompt is targeted. With three undocumented required IDs at zero coverage, the description fails to compensate for the schema gap.

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

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

States a specific verb ('Delete') and resource ('a tracked prompt'), which cleanly separates it from delete_ai_visibility_topic or delete_article in the sibling list. It does not, however, explicitly name an alternative or contrast with the prompt-mutating siblings (update_ai_visibility_prompt, move_ai_visibility_prompts).

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

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

The description gives no indication of when to use this tool versus set_ai_visibility_prompt_status, move_ai_visibility_prompts, or update_ai_visibility_prompt, and no prerequisites or warnings about irreversibility. Usage must be inferred entirely from the tool name.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds the one thing annotations cannot express: the delete is non-cascading and child prompts are retained, which materially changes the agent's risk assessment. It still omits irreversibility and any permission 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?

Two short sentences, no filler, with the destructive action stated first and the side effect second. Nothing is padded or repeated from the title.

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

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

For a destructive, three-identifier mutation with no output schema and no annotation-level detail about scope, the description carries real gaps: it never says whether deletion is recoverable or how project/site/topic scoping works. The non-cascade note is the single most important fact and it is present, which keeps this at minimum-viable rather than inadequate.

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

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

Schema description coverage is 0% across three required parameters (projectId, siteId, topicId), and the description explains none of them. Only topicId is loosely implied by the word "topic"; the other two identifiers, and why all three are needed, are undocumented in both places.

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

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

"Delete a topic" gives a specific verb and resource, and "Its prompts are kept" separates it from sibling delete_ai_visibility_prompt by making clear this removes the container, not its prompts. It stops short of naming the sibling explicitly, so it is clear but not fully disambiguating in a 150-tool list.

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

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

There is no when-to-use framing, no prerequisites (e.g. required project/site scope), and no pointer to delete_ai_visibility_prompt for removing individual prompts. The only guidance an agent can infer is from the side note that prompts survive the delete.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this is an irreversible-style mutation. The description adds a genuinely useful scope limitation (published page survives), but omits the things that matter most for a destructive call: whether deletion is permanent, whether related data (keywords, improvements, distribution posts) cascades, and 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 followed by the scope caveat; nothing is wasted. "from Ranklybee" is the only filler, since the product context is already implied.

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, three-required-parameter mutation with no output schema and no annotation explanation of side effects, the description should say more. It is silent on permanence, cascade effects, param meaning, and error conditions, so an agent cannot safely reason about the consequences of calling it.

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

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

Schema description coverage is 0% for all three required parameters, so the description carries the full burden and gives nothing: projectId, siteId and assetId are never mentioned. In particular, assetId is not identified as the article identifier, leaving real ambiguity in a destructive operation.

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

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

Names a specific verb and resource ("Delete an article from Ranklybee") and adds a scope clarification: it does not remove a page already published on the website. The resource is unambiguous against the other delete_* siblings (delete_product, delete_lead_keyword, delete_outreach_template), though no sibling is named explicitly.

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

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

The second sentence sets a boundary — deletion here does not unpublish a live page — which hints at when this is and isn't the right operation. However, it never states prerequisites, when to prefer update_article or a publish/unpublish pathway, or whether the article must be in a particular state to be 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 cover the safety profile (destructiveHint=true, readOnlyHint=false, openWorldHint=false), so the description only needs to add nuance. It adds nothing — no statement of irreversibility, no cascade behavior, no confirmation semantics — so it contributes zero 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 single sentence is free of filler, but it is under-specified rather than concise — it conveys no information an agent could not derive from the tool name. Brevity here reflects a content gap, not efficiency.

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

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

A destructive, no-output-schema delete with three undocumented required IDs is missing the essentials: irreversibility warning, required permissions, and how to obtain the identifiers. Only the annotations carry any behavioral weight.

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?

Three required parameters (projectId, siteId, ruleId) with 0% schema description coverage receive no explanation in the description. It does not say where these identifiers come from or how they relate to the alert rule hierarchy.

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?

'Delete an alert rule' restates the name and title almost verbatim with no additional verb, scope, or distinguishing detail. With siblings like delete_lead_icp, delete_lead_keyword, and delete_outreach_template following identical naming, the agent gains nothing beyond the tool name itself.

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

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

No when-to-use guidance, no mention of prerequisites, and no reference to the sibling list_lead_alert_rules that would supply the ruleId. The agent must infer the entire workflow from the name.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is covered structurally; the description adds nothing beyond restating deletion. It does not say whether the deletion is permanent, whether it cascades to associated leads/keywords, or whether a confirmation is required.

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

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

A single short sentence is front-loaded and free of waste, but that brevity comes from under-specification rather than discipline. It is minimally structured but not informative.

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 three undocumented required IDs and no output schema, the description should at least indicate scope and permanence. It leaves the agent without enough to call it safely or 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?

All three required parameters (projectId, siteId, icpId) have 0% schema description coverage and the description mentions none of them or their scope/format. Unlike a zero-parameter tool, this definition leaves the identifiers entirely unexplained.

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

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

The description gives a specific verb ("Delete") plus a resource ("customer profile"), but the resource is named loosely and doesn't match the tool's own title ("ideal customer profile") or the icpId parameter. It also offers no differentiation from the many nearby delete siblings such as delete_lead_keyword or delete_outreach_template.

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

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

There is no guidance on when to delete an ICP versus updating (update_lead_icp) or deactivating it, no prerequisites, and no mention of the project/site scope needed. The agent must infer all selection context.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds nothing on top of that — no statement about irreversibility, cascade effects, required permissions, or confirmation requirements. It merely repeats the destructive verb that the annotations already encode.

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

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

A single short, front-loaded sentence with no filler, so there is nothing wasteful to trim. However, it is concise to the point of being under-specified rather than efficiently informative.

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, zero-annotation-detail, three-required-parameter operation with no output schema, the description should at minimum identify the resource boundary and the irreversibility of the action. It leaves the agent without the information needed to invoke it confidently.

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

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

Schema description coverage is 0% and the description says nothing about projectId, siteId, or keywordId. The identifiers are somewhat self-describing by name, but the description contributes zero semantic value for a tool that requires all three correctly scoped IDs to avoid deleting the wrong record.

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 is essentially a restatement of the title ("Delete a lead keyword" vs "Delete a monitoring keyword"), swapping in a different noun for the resource. It never clarifies which entity is being deleted (a lead keyword vs. an outreach or article keyword) or how it differs from the many sibling delete_* and remove_* tools. Without opening the schema an agent cannot tell why it should pick this over remove_outreach_keyword or delete_lead_alert_rule.

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

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

There is no when-to-use guidance, no prerequisites, no mention of alternatives, and no warning that this is an irreversible removal. For a destructive tool in a family containing several near-identical keyword deleters, this omission is actively unhelpful.

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 openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that: no note on irreversibility, whether drafts/scheduled sends referencing the template are affected, or whether confirmation is required.

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

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

One short front-loaded sentence with zero padding, which is structurally clean. But its brevity comes from under-specification rather than efficiency, since no substantive information beyond the name is conveyed.

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, three-required-parameter mutation with no output schema and no parameter documentation, the description is too thin. An agent cannot determine scope, side effects, or failure modes from either the description or the schema.

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

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

Schema description coverage is 0% across three required parameters (projectId, siteId, templateId). The parameter names are largely self-evident, but the description supplies no scoping semantics — e.g., that the template must belong to the given project/site or what happens on a mismatch.

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 ('Delete an email template'), so the core action is identifiable. However, it says 'email template' rather than 'outreach template', and with siblings such as list_outreach_templates, create_outreach_template, and update_outreach_template, plus unrelated template-like resources (distribution pages/posts), it does nothing to anchor the tool to the outreach domain.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no reference to alternatives such as update_outreach_template (which is the safe action if the template is still needed). The agent must infer all routing from the tool name alone.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: it does not state whether deletion is permanent or reversible, whether it requires elevated permissions, or what happens to dependent 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?

A single grammatical, front-loaded sentence with no wasted words. It is concise but achieves that partly through under-specification rather than disciplined editing.

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 mutation with no annotations detail beyond hints, no output schema, and zero parameter documentation, the description is far too thin. An agent cannot confirm scope, permanence, or parameter roles before invoking an irreversible operation.

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

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

Three required parameters (projectId, siteId, productId) with 0% schema description coverage, and the description supplies no meaning for any of them. The phrase 'from the catalog' hints at scope but does not map to projectId/siteId, so the description fails to compensate for the documentation gap.

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

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

Clear verb+resource: 'Delete a product from the catalog' tells the agent exactly the operation and object. However, it does not distinguish itself from siblings such as set_product_status (likely a soft status change) or update_product, leaving ambiguity about hard vs. soft removal.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives like set_product_status for deactivation. The agent must infer from the name alone when this is the right tool versus 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 declare readOnlyHint=false, so this is a mutating/job-launching call, yet the description's verb 'Scan' reads as a passive read and never says that improvement records are created, whether the work is async, or how long it takes. The presence of an idempotencyKey parameter also implies retryable creation semantics that the description never explains. Not a strict contradiction, but the description undersells the mutation.

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

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

A single front-loaded sentence with no filler or repetition. Efficient, though the brevity is partly under-specification rather than disciplined concision.

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

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

For a 3-required-param, mutating, likely long-running scan with no output schema, the description is missing the essentials: what it creates, whether results arrive synchronously or must be fetched via get_article_improvements, and why an idempotency key is mandatory. An agent could invoke it but cannot predict the outcome.

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?

Three required parameters with 0% schema description coverage and the description adds nothing. projectId and siteId are self-evident from naming, but idempotencyKey (max 160, min 8) needs an explanation of what duplicate-submission protection it provides, and the description supplies 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?

Specific verb+resource: 'Scan published articles against search data for new refresh opportunities.' An agent knows the general action is a discovery/scan over published content. However, it does not distinguish itself from close siblings such as generate_article_improvement or get_article_improvements, so an agent cannot tell which of those four improvement tools to pick 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 sentence implies a discovery use case but gives no explicit when-to-use, no prerequisites, and no alternative to prefer (e.g. 'use generate_article_improvement once you have the scan results'). With a dense sibling cluster of *_article_improvement tools, this is a real gap.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the agent knows this is a non-destructive mutation. The description adds nothing about what dismissal actually does — whether it is reversible, whether the improvement is hidden or archived, who can dismiss, or whether the reason is surfaced to anyone. For a mutation tool the disclosure burden is largely unmet.

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

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

A single short, front-loaded sentence with no filler or repetition. It is efficient, though the brevity reflects under-specification rather than tight editing.

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 four-required-parameter mutation with no output schema and no schema descriptions, the definition is too thin. An agent gets no information on side effects, reversibility, prerequisite state (e.g., the improvement must exist and not already be applied), or what the reason is used for.

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

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

Schema description coverage is 0% for four required parameters. The description mentions 'with a reason,' which confirms the reason field's purpose and implicitly that it is mandatory, but projectId, siteId, and improvementId are undocumented in both the schema and the description, leaving three of four parameters with no semantic guidance.

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 (dismiss) and resource (an improvement opportunity) plus the required reason, so an agent can tell what the tool does at a glance. It does not differentiate from closely named siblings such as decide_article_improvement, submit_article_improvement, or apply_article_improvement, which is the only thing keeping it out of the top band.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as applying or deciding on the improvement instead. The agent must infer from the tool name alone that this is the rejection path for an improvement opportunity.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, and 'Hide' is consistent with a non-destructive mutation, so there is no contradiction. However, the description adds nothing beyond that: it does not say whether the hide is reversible, whether the lead can be restored, or what happens to the underlying mention.

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

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

A single short sentence that is front-loaded with the verb and resource and contains no filler. It is efficient, though the terseness contributes to the specification gaps rather than being a virtue in itself.

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 state-changing tool with three fully undocumented parameters and no output schema, the description is too thin. An agent gets no information about reversibility (despite a restore_lead sibling existing) and cannot map any argument to its meaning, so it is not complete enough to call reliably without reading the schema.

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

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

All three required parameters have 0% schema description coverage and the description supplies no meaning for any of them. Notably it does not explain why a lead is targeted via mentionId (with projectId and siteId) rather than a lead identifier, which is exactly the kind of ambiguity the description should resolve.

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

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

Names a specific verb ('Hide') and resource ('a lead') plus the qualifying condition ('not relevant'), so the agent knows the operation. It does not, however, distinguish this from adjacent actions in the sibling list such as restore_lead, reject_prospect, or set_lead_feedback, leaving boundary cases to inference.

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

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

The phrase 'a lead that is not relevant' hints at a trigger condition but gives no explicit when-to-use guidance and never names an alternative. There is no mention of restore_lead for undoing the action or of any other lead-disposition tool, so the agent must guess at routing.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation profile is partly covered. The word 'Replace' adds useful context that existing text is overwritten, and 'approve it for publishing' discloses a state transition. However, it says nothing about permissions, reversibility of approval, or side effects on the publishing pipeline.

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 tight sentence with the action front-loaded and zero filler. It is efficient, though extremely brief for a tool with four undocumented parameters.

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

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

For a write-and-approve mutation with no output schema and four parameters at 0% schema coverage, the description is too thin. It does not explain parameter roles, approval consequences, or expected results, leaving significant gaps the structured fields do not fill.

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

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

Schema description coverage is 0% across four required parameters (projectId, siteId, postId, body), and the description adds no mapping to them. It only obliquely refers to 'a post's text', leaving the identity/scoping parameters entirely unexplained in prose.

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

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

The description names a specific verb ('Replace') and resource ('a post's text') plus a distinct second action ('approve it for publishing'). This separates it reasonably from siblings like approve_distribution_posts and regenerate_distribution_post, though it does not explicitly name those alternatives.

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

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

There is no when-to-use guidance, no prerequisites, and no reference to the sibling tools that handle approval-only (approve_distribution_posts) or rewrite-only (regenerate_distribution_post) workflows. The agent must infer selection from the description alone.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the agent knows this writes but is not flagged destructive, yet the description adds nothing beyond that. It does not say whether the exclusion is reversible (a sibling restore_ tool implies it is), whether existing mentions/comparison data is affected, or what the caller must own to make the change.

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

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

A single short sentence is front-loaded with no redundancy, which is good, but it is under-specified rather than genuinely concise for a three-parameter mutation tool. There is room for one more clause about scope or reversibility without bloating it.

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

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

With no output schema, three undocumented required parameters, and annotations that only cover safety hints, the description should explain the identifiers, the effect on comparison data, and the reciprocal restore tool. None of that is present, so an agent cannot reliably invoke it beyond guessing.

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

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

All three required parameters (projectId, siteId, name) have 0% schema description coverage, so the description carries the full burden and fails it. Only the word 'brand' loosely gestures at the name parameter; projectId and siteId are never explained, and no format or example is given.

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 recognisable action (leaving a brand out) and a scope (competitor comparisons), which is marginally more specific than the tool name. However, it essentially restates the name and title and never names the sibling it belongs to, such as restore_ai_visibility_brand or add_ai_visibility_competitor, so an agent gets no differentiation signal.

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

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

There is no when-to-use guidance, no preconditions (e.g. the brand must already exist in the competitor set), and no mention of the obvious inverse tool restore_ai_visibility_brand for undoing the exclusion. The agent is left to infer everything from the name.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, so the safety profile is partly covered. The description adds a genuinely non-obvious behavioral fact — that the call draws down a metered contact allowance — but omits what happens on exhaustion, whether results are cached, and what a lookup actually returns.

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 scope, no filler. It is efficient, though the small size reflects thin content rather than disciplined editing.

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

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

A four-parameter, all-required, credit-consuming tool with no output schema and 0% parameter coverage needs the description to carry more than it does. Nothing explains the identifier parameters, the idempotency requirement, or the shape of the result.

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

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

Schema description coverage is 0% across four required parameters, and the description documents none of them. It only vaguely implies site/prospect scoping, and says nothing about idempotencyKey, which is the parameter most in need of explanation given the metered, retryable nature of the call.

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

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

States a specific verb and resource: look up a contact / who to email at a prospect's site. An agent can distinguish this from siblings like select_prospect_contact or verify_contact, though those distinctions are only implied, not stated.

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

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

The description says it consumes the plan's contact allowance, which hints at cost but gives no explicit when-to-use, when-not-to-use, or alternative (e.g. select_prospect_contact vs a fresh lookup). No prerequisites or sequencing guidance.

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

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

Annotations only cover the safety profile (not read-only, not destructive, closed-world), so the description carries the rest of the behavioral burden and does so well: it discloses that the call consumes the plan's article allowance (a quota/cost effect), that it is long-running ('takes a few minutes'), and that completion must be polled via get_article. These are non-obvious traits an agent cannot infer from the annotations or schema.

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

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

Two short clauses with zero filler; the core action and precondition come first, then the operational notes. 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 mutating, asynchronous generation call with no output schema, the description covers latency, quota, and the polling path adequately. It leaves a real gap on inputs, notably the mandatory idempotencyKey and the relationship between projectId, siteId, and briefId, which an agent must guess.

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

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

Schema description coverage is 0% across four required parameters, so the description must compensate and largely does not. It hints at the brief via 'brief' but never explains briefId, siteId, projectId, or the required idempotencyKey, whose length constraints and duplicate-suppression purpose go unstated.

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 (write the article) and names the precondition (an approved brief), which separates it from generate_content_plan and publish_article in the same family. It stops short of explicitly contrasting with the nearest siblings, but the act and object are unambiguous.

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

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

Gives a clear trigger condition ('for an approved brief') and the follow-up action ('poll get_article'), which tells the agent both when to call it and what to do next. It does not say what to do when no approved brief exists, so it is not fully 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 establish it is a write (readOnlyHint=false), non-destructive, closed-world operation, so the safety bar is lower. However the description adds nothing beyond that: it does not say whether output is persisted as a draft, whether it consumes or requires an improvement in a given state, or how idempotency behaves, which matters for a mutating generation tool.

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

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

A single front-loaded sentence with no filler, which is structurally clean, but it is undersized for a four-parameter mutating tool and omits information the agent needs, so brevity here reads as under-specification rather than economy.

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

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

For a non-read-only generation tool with no output schema, 0% parameter coverage, and only generic annotations, the description should carry the load on state changes, idempotency, and result handling. It does none of that, leaving the definition incomplete 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 0% across four required parameters. 'For one opportunity' loosely gestures at improvementId, but projectId, siteId, and especially the required idempotencyKey (8-160 chars) are entirely unexplained in both schema and description, leaving the agent to guess their meaning and values.

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 verb+resource is identifiable ('write the improved version of an article'), but 'for one opportunity' uses undefined domain jargon and the description does nothing to separate this from the dense family of siblings such as generate_article, apply_article_improvement, update_article_improvement, and compare_article_improvement.

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

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

There is no statement of when to use this versus alternatives, no prerequisites (e.g. whether an improvement must first be detected), and no mention of the natural next step (apply/submit/compare). The only hint is 'one opportunity', which is not actionable guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the operation consumes 'the plan's content allowance,' a quota/consumption trait not visible in the schema. It omits async/return behavior and idempotency semantics.

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 action front-loaded and no filler. Efficient, though the second sentence is the only piece of real added 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 non-read-only generation tool with no output schema, three undocumented parameters, and no stated prerequisites or result shape, the definition leaves too much unsaid. An agent knows what it does but not what it needs or what it gets back.

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

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

Schema description coverage is 0% and the description names no parameters at all. The non-obvious idempotencyKey (8-160 chars) and the projectId/siteId pairing are left entirely undocumented, so the description fails to compensate for the coverage gap.

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

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

Clear verb+resource ('Generate a new content plan') plus the inputs it draws on ('site profile and keyword research'). It does not differentiate from close siblings such as decide_content_plan or activate_content_plan, so an agent must infer the distinction.

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

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

No when-to-use context, no prerequisites, and no mention of the sibling tools that operate on the same plan (decide_content_plan, activate_content_plan, get_content_plan). The only constraint given is the allowance note, which is not usage routing.

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

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

Annotations declare readOnlyHint=false with destructiveHint=false, leaving the side-effect profile ambiguous, and the description resolves it usefully: the draft is generated but not published, the user posts it. That is real context beyond the annotations. It still omits what happens on regeneration or how the idempotency key affects repeat calls.

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 purpose front-loaded and the side-effect caveat immediately after. No filler; 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?

The non-publishing behavior is covered, which is the most important unknown for a generation tool with no output schema. But with 6 parameters at 0% coverage and no output schema, an agent still lacks guidance on idempotencyKey, regenerate, and the required identifiers, so the definition is only marginally sufficient.

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

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

Schema description coverage is 0% across six parameters, so the description carries the full burden, yet it only alludes to 'the chosen tone' and never explains the peer/expert/founder enum, regenerating, siteId, mentionId, projectId, or the required idempotencyKey. Most parameters are undocumented in both places.

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

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

States a specific verb (draft) and a specific resource (a reply to a lead's post), which is enough to tell it apart from generic generation tools. However, it does not differentiate itself from the sibling update_lead_reply, which an agent could easily confuse with this one.

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

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

The description says nothing about when to use this tool versus update_lead_reply, prepare_outreach_draft, or create_outreach_draft. The clause 'Nothing is posted' clarifies workflow outcome but is not usage guidance or an exclusion, so an agent gets no routing help.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds one real behavioral fact — that the full (untruncated) text body is returned — but says nothing about failure modes when an ID is unknown or about permissions.

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

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

A single front-loaded sentence with no filler and the scope constraint ('one') placed before the resource. Efficient, though its brevity leaves the under-specification unaddressed.

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

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

For a tool requiring three undocumented identifiers and returning full text with no output schema, the description is too thin — it does not indicate the ID hierarchy, expected return shape, or the error behavior for a missing run.

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

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

Schema description coverage is 0% for three required parameters (projectId, siteId, runId), and the description supplies no parameter meaning at all. It does not explain that the IDs must form a consistent hierarchy or where they are obtained, so it fails to compensate for the coverage gap.

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

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

States a specific verb ('Read') and resource ('one recorded AI answer') and scopes it to a single record, which contrasts with the several list_* siblings. It does not, however, clarify how an 'AI answer' relates to the sibling concepts list_ai_visibility_prompt_runs or get_ai_visibility_citations, so the agent must infer the relationship.

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

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

No when-to-use guidance, no prerequisites, and no named alternative. The agent is left to infer that this is called after listing prompt runs to retrieve one answer's text, which is implied at best.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds no behavioral context beyond that — nothing about time-range semantics, engine coverage, data freshness, or what the comparison returns.

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

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

A single front-loaded sentence with no filler or repetition. It is well-formed, though its brevity comes at the cost of the missing detail noted elsewhere.

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

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

For a 7-parameter tool with fully undocumented schema fields, an enum set of seven engines, no output schema, and several overlapping sentiment siblings, one sentence of description is insufficient. An agent lacks enough to invoke it correctly or route to it reliably.

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

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

Schema description coverage is 0% across 7 parameters, so the description must carry the burden, but it only obliquely gestures at the 'rival' concept ('its rivals'). Required projectId/siteId, the from/to date range, and the singular 'engine' vs. plural 'engines' distinction are all unexplained.

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

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

States a clear verb ('compare') and resource (how favorably AI answers describe brand vs. rivals), which is more specific than a bare name restatement. However, it does not distinguish itself from close siblings like get_ai_sentiment_overview or get_ai_sentiment_driver, leaving the agent to guess which sentiment tool yields the benchmark view.

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

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

There is no when-to-use guidance, no mention of prerequisites (e.g. brand/competitor setup requirements), and no routing to or away from the sibling sentiment and AI-visibility tools. The agent must infer usage from the name alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely non-obvious behavior: 'the summary and tasks are written on first read', a lazy-generation side effect that affects latency and idempotency. It does not mention permissions or rate limits, so it is strong but not exhaustive.

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

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

Two compact sentences with zero filler, front-loading the core read action and the returned artifacts before the side-effect and provenance notes. Every clause carries information an agent needs.

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

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

There is no output schema, and the description usefully sketches the return payload and the write-on-first-read behavior. However, for a 7-parameter tool with 0% schema coverage and no annotations covering inputs, the near-total silence on the date-range and engine filters leaves the definition only minimally complete.

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

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

Schema description coverage is 0% across 7 parameters, so the description carries the full burden. It explains only themeKey's provenance and says nothing about from/to date scoping, the engine/engines filter, or projectId/siteId, leaving six parameters with no semantic guidance anywhere.

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

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

States a specific verb and resource ('Read one sentiment theme') and enumerates what it returns (quotes, suggested tasks). It explicitly distinguishes itself from the sibling get_ai_sentiment_overview by naming it as the source of themeKey, so an agent can route between the two without opening either schema.

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

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

The mention that 'themeKey comes from get_ai_sentiment_overview' establishes the required call ordering and the prerequisite tool, which is real usage guidance. It stops short of stating when not to use this tool or what to do with the returned tasks, so it is clear context rather than a full when/when-not rule set.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the read covers both overall positivity and the driving themes, but says nothing about default time windows, engine scoping, or aggregation behavior for a six-parameter analytical tool.

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

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

A single front-loaded sentence with no filler or repetition. It is efficient, though the terseness contributes to the gaps in usage and parameter guidance rather than offsetting them.

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 six-parameter analytics tool with 0% schema description coverage and no output schema, the description omits date-range behavior, engine selection semantics, and how results are scoped or aggregated. An agent could call it, but only by guessing at the filters.

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

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

Schema description coverage is 0% across six parameters, so the description carries the full burden and fails to explain the from/to date window, the single engine vs. engines array (with maxItems 10), or the required projectId/siteId scoping. 'Themes driving it' loosely gestures at a breakdown but adds no parameter-level meaning.

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

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

States a specific verb (read) and resource (AI sentiment overview of the brand), plus the substantive content: positivity of AI answers and the themes driving it. It does not, however, distinguish itself from close siblings like get_ai_sentiment_benchmark or get_ai_sentiment_driver, so the agent cannot tell which sentiment view to pick.

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

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

No when-to-use guidance, no prerequisites, and no mention of the sibling sentiment tools (benchmark, driver) that clearly overlap. The agent is left to infer when this overview is preferred over the 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds some output-shape context (cited domains/pages plus non-mentioning domains) but says nothing about auth, scope limits, or pagination.

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

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

A single efficient sentence with the action front-loaded. The second clause is slightly muddled but there is no filler or repetition.

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

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

For a 9-parameter query tool with no output schema and no annotation-level detail beyond read-only, the description omits filtering semantics and result scope. It is not complete enough for an agent to call it precisely.

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?

Nine parameters at 0% schema description coverage, yet the description explains none of them. Date range (from/to), engine vs engines, category vs categories, and monitorId filtering are all left undocumented, so the description fails to compensate for the schema gap.

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

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

States a clear verb+resource: read the domains and pages that AI answers cite. However the trailing clause 'the domains that never mention the brand' is ambiguous and no sibling is named, so an agent cannot easily distinguish it from get_ai_visibility_domain_pages.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives in a crowded ai_visibility family (overview, competitors, domain_pages, brand mentions). The agent is left to infer when this is the right call.

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