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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, and the description still adds real behavioral context: it is free, it costs nothing when a matching page already exists, it never creates a picture, and any removal of an old page requires the owner's explicit say-so. That is meaningful disclosure beyond the structured hints for a quoting tool.

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

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

Front-loads the key fact ('Free') and the core behavior in the first sentence, with the operational instruction last. The makeRoom sentence is a slight digression but earns its place by covering the site-full edge case; nothing is 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?

There is no output schema, so the description must carry the return values, and it names the three that matter (price, existing-page check, site readiness). For a 7-parameter nested-schema tool that is adequate, though the exact response shape and how platform/accountId affect the quote are left implicit.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns more by explaining the two input paths — a live adId is read by Soclo, while a draft supplies its own words via the ad object and draftId — which is the non-obvious semantics an agent needs. It does not touch accountId/adAccountId/libraryAssetId, leaving those entirely to the schema.

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

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

States a specific verb (quote) and resource (a page for an ad) and immediately says what the result is: the credit price for a matching page on the owner's Soclo website. It also names two extra return facts (whether an identical page already exists, whether the site is ready), which separates it cleanly from soclo_ad_pages_create and soclo_ad_pages_preview.

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 closing line 'Show the owner the price before create' gives an explicit ordering rule that routes the agent to this tool ahead of soclo_ad_pages_create. The capacity paragraph explains the fallback path (makeRoom, offer to the owner, remove only on their say-so), but no explicit when-not condition or alternative quote tool is named, so it stops short of a full 5.

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