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

Annotations only cover safety (readOnlyHint=true, openWorldHint=false), while the description adds substantive behavior: 300-character truncation of long text blocks, explicit exclusions (email-sync credentials, tracking pixel IDs), and the meaning of suspended: true plus the remediation path and support contact. This is exactly the kind of context annotations cannot convey.

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

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

Three dense sentences, front-loaded with what is returned before the parameter rule and the suspension caveat. Every clause carries information, though the long enumeration of content-block types is slightly heavier than needed.

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

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

An output schema exists, so return-value structure is already covered, yet the description still flags the two things a schema cannot express: truncation of long text and withheld fields. Combined with the suspended-state semantics and the siteId omission rule, an agent has everything needed to call and interpret this tool.

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

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

The single siteId parameter has 0% schema description coverage, so the description must compensate, and it does: it explains when siteId may be omitted entirely (single-site teams). It stops short of stating the expected ID format or where to obtain one, which list_mini_sites presumably supplies.

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

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

States a specific verb and resource ('Read one bio page in full') and then enumerates the actual contents returned: profile header, social icons, content blocks, SEO metadata, theme and auto-pin settings. An agent can immediately distinguish this single-site read from the sibling list_mini_sites.

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

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

Provides a concrete selection rule for the optional parameter: 'Omit siteId when the team has exactly one site.' It also implicitly scopes the tool to reading one page versus listing many, but it never names list_mini_sites or get_mini_site_analytics as alternatives, so the routing guidance is clear but not exhaustive.

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