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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

It routes the evidence concern elsewhere ('written with add_evidence and read from get_profile') and mentions add_topics withholding colliding topics, which gives some context about adjacent tools. But it never states when to call update_profile itself versus approve_profile or upsert_post, so guidance is fragmented and implicit.

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