Convika

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds genuinely new consequences: future control moves to this workspace, existing URLs persist as frozen continuity routes, and page data, forms, analytics, and history are not copied. That is exactly the impact information an agent needs before a destructive, irreversible-feeling activation.

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 precondition and the confirmation requirement are front-loaded in the first two sentences, followed by the consequences. Every sentence carries distinct information; nothing restates the title or annotations.

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

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

For a single-parameter, no-output-schema mutation tool the description covers authorization gating, scope of change, and data-continuity semantics thoroughly. It does not say what the call returns or how success/failure of activation is reported, which is the only remaining gap.

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

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

Only one parameter (attemptId), and schema description coverage is 100% with the schema stating it is 'the verified domain control attempt ID to activate.' The description adds no format, sourcing, or validation detail beyond that, so the baseline 3 is appropriate.

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

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

States a specific verb ('activate') plus the exact resource ('custom-domain control handover') and pins the precondition ('after DNS TXT verification has completed'). This clearly separates it from the sibling verification/setup tools (start_domain_control_verification, check_domain_control_verification, setup_custom_domain) without needing their schemas.

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

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

'Use only after explicit user confirmation' is an explicit gating condition, and the verification-complete prerequisite tells the agent when in the pipeline to call it. It stops short of naming the sibling tools to call first or when-not-to-use alternatives, keeping it at a strong 4 rather than a 5.

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 read-only, idempotent, non-destructive, closed-world, so the description spends its budget on genuinely non-obvious behavior: what the response contains (aggregate metrics, top drivers, findings, evidence, recommendations), the Pro/MAX plan gate for long periods, and that the response echoes timeZone/timeZoneSource/timeZonePending. The 90d caveat that change figures come back null with a mismatched timeZone, and that 180d/365d/all ignore the passed zone and echo it as requestedTimeZone, are exactly the surprises an agent would otherwise trip over.

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

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

Purpose and usage are correctly front-loaded, but the time-zone material sprawls across two long paragraphs with overlap ("it changes only this response" restated as "affects only this response: the workspace's time zone stays as it is"). The IANA-name examples are repeated in both the description and the schema's timeZone description. Tightening to roughly half the length would lose no information.

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

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

With no output schema, the description carries the return-value burden and does so by enumerating the diagnosis sections and ruling out raw events. Plan gating and time-zone edge cases are covered. Minor gaps: botFilter's diagnostic use case and whether recommendation/finding counts are bounded are untouched.

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, and the description earns above that by explaining interactions the schema does not: period and timeZone are coupled (90d null changes; summary-based periods ignore the zone), and today's row is partial. botFilter is left entirely to the schema, which does cover it adequately.

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 ("Analyze a landing page's aggregate analytics") and names the distinct deliverable ("compact diagnosis with prioritized next actions"). It also carves out what it is not ("does NOT return raw event logs or form submission payloads"), which separates it from get_analytics_detail-style siblings. It stops short of naming which sibling to use for raw metrics or timeseries.

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?

"Use when the user asks what to improve, why conversions changed, whether traffic quality is healthy, or what to test next" gives four concrete triggering intents an agent can match against a user request. The exclusion of raw logs/payloads adds a clear when-not condition. There is no explicit routing to get_analytics_summary, detect_trend, or query_timeseries for the adjacent cases.

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 (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: attribution counting rules, bot/scanner exclusion, the 3-month window, the conditional orders block gated on orders:read, and timezone resolution including timeZonePending.

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

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

Front-loaded with purpose and usage before the dense behavioral detail, and nearly every sentence carries information. It is long and the timezone paragraph is heavy, but nothing is clearly 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?

No output schema exists, and the description compensates by enumerating the returned fields, the conditional orders addition, and the timezone metadata fields (timeZone, timeZoneSource, timeZonePending). An agent has enough to call it and interpret 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains what '(direct)' and '(none)' mean for the dimension values, that timeZone affects only this response and never the workspace setting, and how attributionCoverageRate is computed.

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 ('Analyze traffic source quality using aggregate source/UTM metrics and attributed conversion events') and enumerates the exact output metrics, making it clearly distinct from get_analytics_summary, get_analytics_detail, and query_cta_performance.

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 an explicit trigger ('Use when the user asks which referrers, campaigns, UTM sources, mediums, or campaigns are working') and an explicit exclusion ('does NOT return raw event logs or form submission payloads'). It does not name sibling tools as alternatives, so it falls short of a 5.

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 as a read-only, idempotent, non-destructive, closed-world call, so safety is covered. The description adds genuinely new context beyond those hints: this is a polling operation whose pending state is expected, and its result gates the handover flow. It does not describe the shape or distinction of the returned statuses, which is the remaining 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?

Two short sentences with zero padding; the core action is front-loaded and the follow-up instruction follows immediately. Every clause carries operational 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 one-parameter read-only check with strong annotations, the description covers the action, the branch behavior, and the downstream gate, which is most of what an agent needs. It stops short of characterizing the possible return states (verified / pending / failed), so the agent must infer the response vocabulary.

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

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

There is a single required parameter with 100% schema description coverage, and the schema already explains that attemptId comes from start_domain_control_verification. The description adds no format, sourcing, or lifecycle detail beyond that, so the baseline 3 applies.

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

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

The description names a specific verb and resource: checking whether the DNS TXT record for a Convika domain control verification attempt has propagated. It is clearly distinct from get_domain_status and start_domain_control_verification by its propagation-checking scope, though it never names a sibling explicitly to force 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?

It states the condition under which the result is actionable ('If still pending, tell the user to keep the TXT record in DNS and check again shortly') and gives an explicit exclusion against a named sibling workflow ('Do not activate handover until this tool reports verified'). When-to-use, what-to-do-on-pending, and the gating condition are all present.

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?

Beyond the annotations, the description discloses key behavior: single-use by default, 14-day default expiry, auto-unpublish of unclaimed pages around 30 days, URL-preserving ownership transfer, free recipient plan, and a recipientGets field to quote. These are exactly the operational details an agent needs before invoking the 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?

The description is front-loaded with the core action and uses bullets for operational constraints, making it skimmable. It is somewhat long and repeats the “no card” benefit, but most sentences carry relevant workflow or behavioral information.

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

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

For a mutation tool with no output schema, the description is highly complete: it covers prerequisites, ownership-transfer behavior, expiry, single-use limits, recipient terms, and what the response contains. An agent has enough information to call it correctly and explain the outcome to a user.

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

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

Schema description coverage is 100%, so siteId, maxClaims, and expiresInDays are already well documented structurally. The description adds useful context about defaults and single-use behavior, but it does not add parameter-level syntax or constraints beyond what the schema already provides.

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: create a claim link bound to a landing page so ownership can transfer. It clearly distinguishes this from building or publishing the page by naming the outreach workflow and the exact outcome, so an agent can identify the tool without opening the schema.

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

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

The description gives clear usage context: it is for the “I built you a page” outreach and requires the page to already exist and be published. It names prerequisite siblings (create_landing_page_preview, publish_site) but does not explicitly state when not to use this tool versus alternatives such as referral links.

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 state readOnly=false, destructive=false, and idempotent=false, but the description adds substantial context beyond them: automatic submission storage, honeypot spam protection, optional email notifications, plan limits (50 free submissions/month, held entries up to 1,000, Pro unlimited), and the fact that preview submissions validate but are not stored or trigger webhooks. It also specifies how answers are stored as text and how checkbox groups are joined.

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 front-loaded with purpose and usage, but it is extremely long and includes a full HTML form plus a lengthy JavaScript fetch example. While relevant to correct embedding, this level of detail bloats the tool description and could be trimmed or moved to separate 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?

For a complex mutation tool with no output schema, the description covers prerequisites, workflow, plan limits, submission behavior, field design, and embedding requirements. An agent has enough information to invoke the tool correctly and follow up with the right sibling tools.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful guidance beyond the schema by instructing the agent to tailor fields to the page (e.g. order forms need tel, select, address, quantity; reservation forms need date and party size) and by mapping field types to HTML inputs and storage behavior.

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

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

The description opens with a specific verb and resource: 'Add a contact form, email signup, or lead capture form to a landing page.' It clearly distinguishes the tool from page-creation siblings by explaining the prerequisite siteId and the create_landing_page_preview workflow.

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

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

It gives explicit when-to-use examples in multiple languages and lists the exact workflow: create_landing_page_preview for new pages, then create_form, then save_page_content, then create_preview. It also names related tools for viewing submissions (get_form_submissions) and embedding (save_page_content).

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?

Beyond the annotations, it discloses important behavior: daily per-workspace page quotas by plan, UTC reset timing, that deleted pages do not restore allowance, and that URL assignment may replace an existing site route when guidance.existingSite is present. It also clarifies the post-creation workflow.

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

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

The description is long but justified by the tool's 11 parameters and routing rules. It is mostly front-loaded and organized, though the Japanese marketing line and some repeated routing details add minor noise.

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

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

For a complex creation tool with no output schema, the description is highly complete: it covers URL/path/subdomain behavior, quotas, follow-up tools, publishing caution, and the existingSite warning. An agent has enough context to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds useful integrated semantics for path, subdomain, and url: first page vs later pages, workspace site naming, and not putting a requested path into subdomain. Other parameters are already well documented 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?

The opening sentence states a specific verb and resource: creating a hosted landing page shell with CDN, SSL, analytics, forms, and versioning. It also explicitly says the tool is equivalent to create_site, which helps an agent distinguish it from sibling creation tools.

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

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

The description gives detailed when-to-use guidance: choose path vs url vs subdomain, use save_page_content after creation, then create_preview before production, and avoid publish_site unless the user explicitly asks. It also flags the guidance.existingSite case and tells the agent to warn before DNS changes.

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

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

Annotations only declare the generic non-read-only, non-idempotent profile; the description adds substantial specifics beyond that: the exact side effects (page creation, goal setup, HTML saved as first version, token-protected preview URL), per-workspace daily quotas by plan, that the count resets at midnight UTC and includes dashboard/uploads/AI/MCP creation, and that deleting a page does not restore allowance. It also flags the DNS-replacement risk when guidance.existingSite is present and warns the user must be told before any DNS 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?

Well front-loaded: the trigger and core behavior come first, then placement rules, quotas, forms, and the publish warning in descending priority. It is long, and the path/url/subdomain paragraph substantially restates what the 100%-covered schema already says, which is the main 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 21-parameter, nested-object, non-idempotent creation tool with no output schema, the description covers what an agent needs: when to call it, where the page lands, quota limits, the multi-step form workaround, and the publish boundary. The mention that siteId is returned compensates for the absent output schema at the level an agent needs to chain calls.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a mental model the schema lacks: workspaces hold sites, each page is a path on one site, and the interplay between path, url, and subdomain (subdomain only for the workspace's first page; url instead of path for a full domain). It stops short of explaining the goals, sections, or designOverrides semantics, which remain schema-only.

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 ('creates the whole page preview in a single Convika call') and positions itself as 'the default tool for a new page', which an agent can act on. However, with near-identical siblings in the list (create_page, create_pages, create_landing_page, create_preview), the description never names them or explains the boundary, so the differentiation is only implicit.

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?

Opens with the triggering condition ('when you have the final HTML of a new page') and enumerates the page types it covers. It gives explicit exclusions ('Do not use publish_site unless the user explicitly asks to publish/go live') and prescribes the follow-on sequence for forms (create_form with the returned siteId, save_page_content, create_preview).

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 idempotentHint=true and destructiveHint=false, and the description explains the mechanism behind that: re-creating the same path yields status already_exists rather than a duplicate, with the existing siteId. It also discloses draft semantics (nothing live until publish_pages/publish_site), the full status enum including limit_reached and failed reasons, per-plan daily quotas with UTC reset and non-restoring deletions, and brand_mismatch behavior for expectedBrandId. All consistent with 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?

Front-loaded with the when-to-use condition, then mutation semantics, then exhaustion routing, then limits — a sensible order and mostly high-signal. Minor waste in the bilingual quoted examples and the keyword parenthetical "(ホームページ, Webサイト, ランディングページ)", which read as search bait rather than agent guidance.

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 creation tool with annotations and a full output schema, the description covers everything an agent needs: what is created, that it is a draft, duplicate handling, failure statuses, quota limits, and where to go for previews or bulk creation. Return-value shape is correctly left to the output schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining 'the HTML as its first saved version' (constraining what html means relative to later edits) and by restating the expectedBrandId guard-rail semantics. It does not add syntax-level detail for path/locale, but the schema already carries that.

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+scope: "Creates the page at path on the workspace's site, with the HTML as its first saved version." It also distinguishes itself from near-siblings by naming create_pages (many at once), create_landing_page_preview, create_preview, and save_page_content.

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?

"Use this tool when making one page of the workspace's site at a known path" gives an explicit trigger condition, and the final paragraph enumerates the alternatives with the conditions that select them (many pages → create_pages; goals+preview in one call → create_landing_page_preview; change HTML later → save_page_content). Nothing is left to inference.

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

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

Annotations declare non-read-only, idempotent, non-destructive, closed-world; the description goes well beyond by explaining that everything is created as a draft, that re-creating an existing path returns already_exists rather than duplicating, the per-page status set (created/already_exists/failed/limit_reached), the 10 MB HTML budget, and the brand_mismatch guard for expectedBrandId. The only real gap is how limit_reached interacts with the daily quota mid-batch, which is stated but tersely.

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?

Usage guidance is front-loaded and essentially every sentence adds operational information (statuses, limits, idempotency, quota). It is dense to the point of being cramped - the daily-quota paragraph runs long and the parenthetical Japanese keyword clusters are noisy - but there is little pure 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 batch mutation tool this is complete: creation scope, draft status, idempotency, per-item statuses, size and count caps, quota by plan, and the cross-workspace guard are all covered, and an output schema exists to carry the detailed return shape. An agent can call it correctly without further questions.

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

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

Schema description coverage is 100%, so path, name, html, locale, and expectedBrandId are already documented. The description adds real semantics beyond the schema (paths within a call must differ, 10 MB aggregate HTML, status vocabulary per page), but not per-parameter format guidance, so the baseline plus a slight bump is warranted.

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 with scope: create up to 20 pages per call on the workspace's site, each as a draft at its own path. It implicitly separates itself from single-page creation ("making many pages ... at once", "A bigger job runs as several calls of up to 20 pages each") and from publish_pages and create_preview by naming what those siblings do.

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?

Opens with an explicit trigger ("Use this tool when making many pages of the workspace's site at once, such as one guide or FAQ page for each question") plus example phrasings. It also names the alternatives: nothing goes live until publish_pages, previews come from create_preview, and large jobs are split into multiple calls of up to 20.

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 description adds substantial behavior beyond the annotations: the preview is token-protected, the URL works for 60 minutes, the live production version is not affected, and custom primary URLs may be used with a managed fallback. These details are exactly what an agent needs to set expectations and avoid mistaking preview for publication.

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 front-loaded with the core action and then layers in timing, safety, URL behavior, and next steps without wasted text. Each sentence contributes useful operational 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?

With no output schema, the description carries the return-value context itself by explaining the tokenized URL, 60-minute lifetime, custom URL path behavior, and fallback URL. Combined with the annotations, it gives an agent enough information to call the tool correctly and interpret 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 100%, so both parameters are already documented in the schema. The description repeats that omitting versionNumber uses the latest saved version, but it does not add syntax or format details beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: generate a shareable preview URL for a landing page before going live. It clearly distinguishes the preview from the live production version and from publish_site, but it does not mention the sibling create_landing_page_preview, so sibling differentiation is incomplete.

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 explicitly says to use this after save_page_content so the user can review before publishing, and it names publish_site as the next step when the user is happy. It also explains that calling create_preview again produces a fresh link and that publishing is required to show the page to other people.

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 mutation/safety profile; the description adds genuinely new behavioral context: per-workspace daily quotas (Free 10 / Pro 100 / MAX 1000, midnight UTC reset, deletions do not restore), the guidance.existingSite case where connecting a URL would replace a live site, and a user-consent gate before DNS changes. It also notes Convika handles hosting, SSL, CDN, and custom domains automatically.

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 scoping rules are front-loaded and the workflow chain is well ordered, but the entry is long and unevenly padded: a Japanese keyword list that carries little selection value for an agent, a full quota paragraph, and stray indentation before 'Where a page goes'. Several sentences could be tightened 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 an 11-parameter creation tool with no output schema, it covers the important gaps: quota limits, path/url/subdomain rules, the guidance.existingSite hazard, and the brand_mismatch outcome. It does not say what the call returns (e.g. the page/site id needed for save_page_content), which an agent must infer from context.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics on parameter interplay: path is a route on the workspace site, subdomain is only for the workspace's first page, url is for a full external URL, and subdomain and url are mutually exclusive. The explicit warning not to encode a path as a subdomain is practical guidance the schema does not state.

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 concrete verb and resource: creates a hosted landing page *shell* with analytics, forms, and versioning, which usefully implies it does not create content. It even claims equivalence to create_landing_page, but that leaves the relationship to create_page/create_pages/create_landing_page_preview unaddressed for a cluster of similarly named siblings.

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

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

Gives an explicit post-creation workflow (save_page_content for HTML, then create_preview, and publish_site only on explicit user request) plus concrete when-to-use rules for path vs url vs subdomain. It falls short of distinguishing this tool from create_page/create_pages, which an agent selecting among near-identical siblings would need.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: the three possible outcomes, what 'stable' actually means (no significant trend at the given alpha), and the hard precondition of at least 4 data points.

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

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

Front-loaded with the method and purpose, then the input shape, then the outputs, then the precondition. Every sentence carries distinct information with no repetition of the schema.

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 present, the description fully compensates by enumerating the return fields (trend, Kendall's tau, p-value, Sen's slope). Combined with the stated preconditions, 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?

Schema coverage is 100%, so the baseline is 3. The description earns above baseline by explaining the semantics of the alpha threshold (it determines whether a trend is declared 'stable') and the interpretation of each return value derived from the inputs.

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 the exact statistical method (Mann-Kendall) and states the verb+outcome: determine whether a series is trending up, down, or stable. It also names the sibling that feeds it (query_timeseries), so an agent can place it precisely among 35+ siblings.

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

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

Gives clear context for use — pass an ordered array such as daily visitor counts from query_timeseries — and states the minimum data requirement. It does not, however, say when to prefer this over other analysis siblings or when a trend test is inappropriate.

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 mark this as destructive, idempotent, and open-world, so the bar is lower. The description adds useful behavioral detail: it stops Convika from serving that exact path after the route map updates, and it describes the main_domain_path refusal case.

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 front-loaded with the core action and confirmation requirement, and the additional workflow notes are relevant. Some sentences, especially the main_domain_path explanation, are dense but still earn their 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 one-parameter tool whose annotations already cover safety traits, the description provides the missing operational context: confirmation, exact effect, route-map timing, special main_domain_path handling, and legacy replacement workflow.

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

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

Schema description coverage is 100% and the single routeId parameter is already documented as coming from list_domain_routes. The description does not add further routeId semantics beyond the schema, so baseline 3 applies.

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

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

The description states a specific verb and resource: disabling one custom-domain route. It is clearly distinct from list_domain_routes and enable_domain_route, and the special legacy-path workflow reinforces the exact scope.

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

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

It gives a strong prerequisite: use only after explicit user confirmation. It also explains the main_domain_path exception and the legacy frozen path replacement sequence, though it does not explicitly mention enable_domain_route as the reversal alternative.

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

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

Beyond the annotations, it discloses that the URL answers again after the route map updates in about a minute, that an unpublished page still returns 404, and that a conflicting page produces route_conflict with existingSiteId. These are meaningful operational behaviors for a mutation 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?

The description is front-loaded with the core action and user-intent examples, then uses bullets for timing and conflict behavior. It is appropriately sized for a mutation tool with non-obvious side effects.

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, the description still explains the success timing, the unpublished-page 404 case, and the conflict result shape. Combined with annotations covering safety and idempotency, it gives the agent enough to call the tool correctly.

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

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

Schema coverage is 100%, and the schema already documents routeId as the id of a disabled route from list_domain_routes. The description reinforces the disabled-status prerequisite but does not add syntax or format details beyond 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?

The description states a specific verb and resource: re-opening one stopped custom-domain route, with the page it had. It clearly distinguishes this from disable_domain_route and list_domain_routes by naming the stopped-route state and the prerequisite lookup.

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

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

It gives explicit when-to-use guidance, including user-intent examples, and says to call list_domain_routes first and pass a route whose status is "disabled". It also covers the conflict case and tells the agent to ask the user before changing anything else.

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 say non-read-only, non-destructive, non-idempotent. The description adds substantial context the annotations cannot: it saves a DRAFT only, never confirms a price or turns orders on, enumerates all four status values and their meanings, and clarifies that a repeat call replaces only an unconfirmed draft (directly relevant given idempotentHint=false).

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

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

Front-loaded with the trigger sentence and organized by topic (draft behavior, statuses, itemModes, buttons, Stripe). It is long and repeats the 'nothing is sold yet' idea more than once, and the Stripe/two-step verification aside is peripheral, but nearly every sentence carries operative 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?

There is no output schema, and the description compensates by documenting status outcomes, setupUrl and sellerMustFinish handoff, and the fulfilmentModes return value. An agent has enough to call the tool and correctly report the result without over-claiming that orders are live.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully extends itemModes: it explains how to infer modes from page content (Zoom consultation → online, PDF/download → digital), that items should be omitted when the page is silent, and that values are proposals stored on the draft with returned fulfilmentModes reflecting what was actually saved.

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

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

The description opens with a precise trigger and outcome: making a Convika page take orders, with concrete instantiations (buy button, order form) and multilingual user phrasings. An agent can immediately tell this apart from read-side siblings like get_orders or content-editing siblings like save_page_content.

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

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

It gives strong when-to-use signals (explicit request patterns in English and Japanese) and post-call instructions (show setupUrl and sellerMustFinish, don't claim the page takes orders yet). It does not explicitly name alternatives (e.g., get_orders for viewing, save_page_content for wiring buttons) as exclusion paths, so it stops short of a full routing statement.

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

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

Goes well beyond the readOnly/idempotent/non-destructive annotations: it enumerates included fields (answers, country, spam score, time), explicitly excludes IP and browser details, and warns that returned content is user-supplied and wrapped in untrusted-data tags with a per-call id. That is exactly the prompt-injection and data-shape context an agent needs and cannot get from structured fields.

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

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

The core purpose and usage condition are front-loaded and every paragraph carries useful content. The parenthetical describing how untrusted-data tags appear in CSV versus JSON is dense and hard to parse in one pass.

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 seven parameters, no output schema, and a read-only profile, the description covers return shape, excluded fields, time semantics, and safety framing well. It omits any hint about pagination limits (max 1000 per call, offset for chunking), which the agent must discover from the schema alone.

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

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

Schema coverage is 100% and every parameter is already documented in-schema, so the description's restatement of ISO 8601 / whole-UTC-day semantics adds little beyond the schema. It does clarify there is no timeZone field and that times are UTC, which is a small genuine addition, but nothing on limit/offset chunking behavior.

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 plus output formats (CSV/JSON) and a target use (spreadsheets, CRM, other tools). It does not differentiate itself from the sibling get_form_submissions, leaving the agent to infer which one to reach for.

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?

"Use when the user wants to download, export, or analyze their form data outside of Convika" gives a clear triggering condition. It stops short of naming the alternative (get_form_submissions) or stating exclusions, so the when-not half is missing.

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

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

Annotations already cover read-only/idempotent safety, yet the description adds substantial behavioral context: Pro/MAX gating for 180d/365d/all, data first recorded 2026-10-25, IPs never stored, only live page fetches counted (not robots.txt/sitemap), and timezone behavior on zone change. It also preempts the most dangerous misreading by stating that available=false and liveDaysAvailable=false mean 'not zero'.

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 use-when trigger is correctly front-loaded and the bullet grouping of totals/verification/referrals helps, but the prose is extremely dense with nested caveats (fetchDayTimeZoneSince, rebuilt zone changes, floor semantics) that overwhelm scanning even though most are substantive. There is no output schema, so much of the length is justified, but it could be tightened.

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

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

With no output schema and a highly complex return shape, the description carries the full documentation burden and does so thoroughly: it defines every top-level field group (totals, verification, byVendor/byToken/byPath/byDay, referrals, liveDaysAvailable) and their edge-case 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: period affects visitorsMethod (unique_in_period vs sum_of_daily_uniques), whether referrals coversPeriod, and which days are read live. siteId gains scope clarification ('One page's') that the schema's one-liner does not fully convey.

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

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

The description names a specific verb and resource ('Returns one page's AI access') and enumerates the exact question types it answers (AI reads of a landing page, which crawlers fetched it, AI-referred visitors). It explicitly separates itself from get_analytics_summary ('Neither is a page view or a visitor in get_analytics_summary'), which is the key sibling confusion risk.

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?

Opens with an explicit use-when clause covering multiple phrasings, including Japanese user utterances ('「AI に読まれている？」「ChatGPT から来た人は？」'), so an agent can route on natural user language. It also states the negative boundary against get_analytics_summary, so the alternative is named and the exclusion 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 cover read-only/idempotent/non-destructive, and the description adds substantially more: 90d changes go null when a non-workspace timeZone is passed, long periods come from daily summaries in the workspace's time zone, requestedTimeZone is reported instead of applied, timeZonePending signals a pending zone switch, and today's row is partial. These are non-obvious edge cases an agent could not infer from 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?

Well front-loaded with purpose and use case, but the multi-sentence time-zone block is dense and partly restates the schema's own timeZone description, including dashboard/settings commentary that an agent doesn't need. It's informative but not tight.

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 4-param read tool with no output schema, the description covers plan gating, period semantics, time-zone behavior, and several result field names, which is close to sufficient. It never sketches the overall response shape (what the breakdown rows contain), leaving a modest gap given there is no output schema to lean on.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics beyond it: it explains why timeZone must be omitted for 90d change figures, that timeZone only affects this response and never the workspace setting, and how the result names the zone used (timeZone, timeZoneSource, requestedTimeZone). botFilter is left entirely to the schema, so it isn't a full 5.

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 (analytics detail/breakdown) and enumerates the concrete dimensions it returns: period comparison, device, UTM, CTA clicks, hourly. It explicitly positions itself against the sibling get_analytics_summary ('Includes everything from get_analytics_summary PLUS'), so an agent can separate the two 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?

Gives concrete use cases ('optimize campaigns, evaluate traffic sources, understand user behavior in detail') and implicitly routes simpler needs to get_analytics_summary via the 'PLUS' framing. It also warns that 180d/365d/all are Pro/MAX only. It stops short of an explicit 'use summary instead when...' exclusion, so it stops at a strong 4.

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 read-only/idempotent safety, and the description goes far beyond them: plan gating for long periods, that timeZone only affects this response and never the workspace setting, that long periods ignore timeZone and report requestedTimeZone, that today's row is partial, and the timeZonePending state. These are non-obvious behavioral facts an agent could not infer from annotations or schema.

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

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

Purpose and usage triggers are front-loaded ahead of the detail, which is the right order. The final timezone paragraph, however, is a dense multi-clause block covering five distinct behaviors that would read better as separate points, costing some scannability.

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, yet the description describes the return shape (daily breakdown, top pages, referrers, country) plus the timeZone/timeZoneSource/timeZonePending fields. For a 4-parameter, read-only analytics call, nothing material needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not: the interaction between long periods (180d/365d/all) and timeZone, and how the response signals which zone was actually used. botFilter is left entirely to the schema, which limits it to a 4.

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

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

The opening sentence names a specific verb+resource and enumerates the actual metrics returned (pageviews, visitors, CTA clicks, referrers). It also pre-empts confusion with get_analytics_detail by scoping 'deeper analysis' elsewhere, so an agent can distinguish it from siblings without opening a schema.

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

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

It gives an explicit trigger ('when the user asks about traffic, performance, conversions, or how their page is doing') and names the alternative for deeper analysis (get_analytics_detail with device/UTM/hourly/comparison). It also warns that its visitor count differs from the dashboard's site overview, a real selection hazard.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds substantial behavioral context: small-sample caveats, untrusted-data tagging, token-based pagination, and the fact that answers reflect one visitor in one country at one moment. It also explains that a check whose answer did not return was given back.

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

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

The description is long, but it is front-loaded with the use case and then organized into return-value sections. The length is largely justified because there is no output schema and the return structure is complex, though some details are dense and could be tightened.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: questions, brand names, saved domains, balance, running checks, per-AI metrics, recent statuses, latest answer flags, target-page details, links, sites, and pagination. It also explains caveats that affect interpretation.

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

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

Schema description coverage is 100%, so the schema already documents cursor, promptIds, and targetPageId. The description adds only light context, such as saying promptIds or targetPageId pick the questions and that cursor comes from resultsShown.nextCursor, which is already 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?

The description opens with a specific use case: when the user asks whether AI answers mention or cite their brand, with concrete examples. It clearly states that the tool returns the workspace's AI answer check results, distinguishing it from run_answer_check, which actually runs checks.

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 explicitly says when to use the tool and gives example user questions in Japanese and English. It also clarifies that nothing is asked unless the user runs run_answer_check or the dashboard button, which prevents misuse as a trigger for new checks.

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?

Beyond the annotations, the description explains return structure, site kinds, hostLabel null behavior, page listing limits (up to 100 per site or roughly 6,000 tokens), and how pageCount/morePages signal omitted pages. This adds substantial behavioral context for a read-only retrieval 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?

The description is front-loaded with usage guidance followed by return details, and most content is relevant. It is somewhat long and includes multiple examples and field explanations, but the length is justified by the complexity of the returned workspace structure.

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

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

Given the rich annotations and output schema, the description still provides enough additional context about when to call it and what the returned workspace contains. It also covers pagination behavior and the meaning of key fields, leaving no major gaps for an agent.

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

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

The tool takes zero parameters, so the baseline is 4. The description appropriately focuses on output semantics rather than inventing parameter 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?

The description clearly states that the tool returns the workspace/brand along with its sites and pages, and it clarifies the brand/workspace naming mismatch. It is distinguishable from list_pages for omitted pages, but it does not explicitly differentiate itself from siblings like get_site or list_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?

It gives concrete usage conditions: seeing sites and pages together, or when many pages are being created or fixed at once, with example user phrases. It also notes that other tools work without calling it first and points to list_pages for pages not shown, though it does not explicitly contrast with get_site or list_sites.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds genuine beyond-schema context: which specific bots each switch controls, that both default to true unless the owner disabled them, that {name}.convika.page pages have no settings here, and that free and paid plans both apply. That is exactly the kind of edge-case and default information annotations cannot express.

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

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

Structure is strong: a trigger clause, a returns clause, then a bulleted breakdown of the two bot switches, followed by usage and scope notes. It is somewhat long with multilingual keyword padding (独自ドメイン, ホームページ, and long bot name lists), but every sentence still carries content an agent would otherwise have to guess.

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, the description fully compensates by naming the returned fields and explaining what each AI-bot switch means. It also covers the ambiguous case (subdomain pages have no settings) and plan scope, leaving nothing an agent needs to call it correctly unanswered.

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

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

Schema description coverage is 100% and the parameter's own description already says 'id or hostname ... leave out to list all.' The description repeats this nearly verbatim ('Pass domain (its id or hostname) for one domain; leave it out to list them all'), adding no new semantics, so the baseline 3 fits.

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 ('which custom domains their workspace has') and enumerates the exact data returned (id, hostname, status, page count, AI-bot switches). It is clearly distinguishable from siblings like get_domain_status, list_domain_routes, and update_domain_settings because it is the settings/listing read.

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 opens with explicit trigger conditions tied to user intents ('which custom domains', 'how many pages one serves', 'whether AI bots may read their site'). It also explains the one-vs-all selection. It stops short of naming sibling alternatives (e.g. get_domain_status) to route away from, which is the only missing piece.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real context beyond that: the returned fields (verification + SSL status), that pending responses include DNS configuration instructions, and the pending_verification → active status flow.

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

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

Front-loaded with the core capability, followed by usage timing, return content, and the status flow. Every sentence contributes 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?

There is no output schema, but the description compensates by describing what is returned (verification status, SSL status, DNS instructions when pending) and the state progression. An agent has everything needed to call it and interpret 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?

Only one parameter and schema coverage is 100%, so the schema fully documents siteId. The description adds nothing parameter-specific, which is the expected baseline when the schema carries the burden.

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 and resource: checks domain verification and SSL activation status. It also names the companion tool (setup_custom_domain) and the status lifecycle, which lets an agent distinguish it from get_domain or check_domain_control_verification without opening a schema.

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

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

Explicit trigger contexts are given: after setup_custom_domain to monitor progress, or when the user asks about domain status. It stops short of stating when to prefer a sibling such as check_domain_control_verification or get_domain, so it misses full when/when-not coverage.

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 safe idempotent read, yet the description goes well beyond them: it defines handledAt, the exact semantics of `waiting` (not handled, not spam, not over the monthly cap, within 14 days), that IP and browser details are withheld, and that each submission is wrapped in an <untrusted-data-…> tag because it is attacker-controlled form input. That last point is essential for an agent handling returned content and is not derivable from any structured field.

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

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

Purpose and usage are front-loaded, and the dense semantics of handledAt/waiting are worth their length. The untrusted-data paragraph restates the same guarantee twice ('untrustedData says so: everything inside was sent by whoever filled in the form'), which is the one place the text could be tightened.

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

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

No output schema exists, so the description carries the return-shape burden and does so fully: per-submission fields, the meaning of handledAt and waiting, omitted fields, time format, and the timeZone marker. An agent can interpret the response without 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?

Schema coverage is 100%, so the baseline is 3; the description earns above it by clarifying that a bare YYYY-MM-DD in startDate/endDate spans a whole UTC day and that all times are ISO 8601 UTC, which resolves genuine ambiguity in date filtering. It adds nothing about limit/offset defaults, but the schema already covers those.

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: 'View submissions collected by a landing page form', and the usage sentence enumerates concrete use cases (leads, form fills, contact requests). It does not name or distinguish the closest sibling, export_form_submissions, so an agent cannot tell view-vs-export apart from the definition 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?

The 'Use when the user wants to check leads, see who filled out their form, or review contact requests' sentence gives clear situational context for invocation. However, there are no exclusions or alternatives mentioned — notably export_form_submissions, which is the obvious candidate when the user wants the data out of the system rather than reviewed.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds real behavioral facts beyond them: the 'stopped: true' page-view-cap condition that limits reads to 'waiting', and that 'hidden' steps are owner-hidden. It also enumerates every returned kind, which matters because there is no output 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?

The use case is front-loaded, which is good, but the middle is a single enormous paragraph enumerating seventeen kinds in unformatted running text, which is slow to parse. The content is mostly load-bearing given no output schema, but a bulleted structure would deliver the same information far more efficiently.

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

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

For a read-only, one-parameter counts tool with no output schema, the description covers trigger conditions, the full return vocabulary, the stopped/hidden edge cases, and where to go for underlying records. Nothing an agent needs to call it and interpret the result is missing.

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

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

Schema coverage is 100% for the single 'host' parameter, so the baseline is 3; the description adds that host must be one of the workspace's sites and points to get_brand as the way to discover them, which the schema does not say. No format or syntax detail is added beyond the schema's example.

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

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

The description opens with a specific trigger ('when the user asks what to do next on a site') and quoted user utterances, then states exactly what is returned: counts of next steps by kind, as the dashboard's 今日やること lists them. It is clearly separable from siblings like get_analytics_summary or get_site_overview because it is framed around action items rather than metrics.

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

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

It gives explicit when-to-use signals in the form of real user phrasings in Japanese and English, and routes drill-down questions to the right siblings ('get_answer_check_results holds the questions and answers, get_search_performance the queries...'). It does not state an explicit when-not-use case beyond the 'Counts only' framing.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered, yet the description still adds substantial unique behavior: no PII returned, spam excluded, test orders listed but not counted, amounts as text in the main currency unit, ISO 8601 UTC times, and a Free-plan monthly cap with omittedOverCap. The only gap is that the shape of the returned summary object is described prose-only rather than in detail.

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

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

Front-loaded with the trigger condition and example queries before the field list and caveats, and nearly every sentence delivers distinct information. It is dense and long — the Free-plan cap explanation and the list of what is not returned could be trimmed slightly — but nothing is wasted or repetitive.

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, the description carries the return contract itself and does so thoroughly: field list, summary contents, currency/unit formatting, and the Free-plan counting caveat with omittedOverCap. An agent has everything needed to call it and interpret 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 coverage is 100% and each of the four parameters is already documented in the schema, including the ISO 8601 format for `since` and the enum for `status`. The description adds nothing parameter-specific beyond reiterating that times are UTC, so the baseline 3 applies.

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

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

States a specific verb and resource ('Returns the newest orders... and a summary over every order that matches') and enumerates the fields returned. It explicitly contrasts with get_order_stats for where orders came from, so an agent can distinguish it from its nearest sibling without opening a schema.

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

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

Gives concrete trigger conditions with example user utterances (「注文は何件来た？」「今日の注文を見せて」) and names the alternative tool (get_order_stats) for source/attribution questions. It also states what is NOT done here — status changes, refunds, payment settings live on the dashboard — which removes a whole class of misrouting.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: counting rules (excludes test, spam, duplicates, declined, cancelled, refunded, unpaid), revenue definition (paid orders, COD once accepted, less refunds), currency returned as text, the Free-plan 50-orders-per-UTC-month cap with omittedOverCap, and the visitor-join limitation that makes analytics conversions estimates. That is exactly the behavioral context an agent needs to trust the numbers.

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 use-case trigger and alternatives are front-loaded and no sentence is pure filler, but the body is a dense single block, and the traffic-source definition is effectively stated twice (once for bySource, once for byArrival). Slightly tighter phrasing would make the caveats easier to scan.

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 carries the return-shape burden and does: orders and revenue totals, by page, by source dimension, and the byArrival split with the named assistant domains. Plan-tier limitations, date semantics, and the visitor-join caveat are all disclosed, leaving nothing an agent needs in order to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning on top by explaining that startDate/endDate are whole days interpreted in timeZone, that leaving both out means all time, and by defining what the bySource grouping actually represents (UTM source/medium/campaign or referrer, with "(none)"). siteId's "only this page" semantics are already fully covered by 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?

The description names a specific verb and resource set — order counts and revenue broken down by page and by traffic source, plus byArrival — and does so in the user's own vocabulary (「どのページが一番売れてる？」「今月の売上」). An agent can separate it from get_orders (raw list) and analyze_source_quality (traffic+orders side by side) without opening either schema.

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

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

It states explicitly when to use it ("Use this tool when the user asks how many orders or how much revenue..."), gives concrete example utterances including Japanese ones, and names the alternative plus the condition that selects it ("For traffic and orders by source side by side, use analyze_source_quality"). Little is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. On top of that the description discloses non-obvious behavior: fields become null if the version wasn't saved with the sections argument of save_page_content, and the default version resolution falls back from production to latest saved. It does not mention side effects, auth, or pagination, but for a read-only structural getter that is minor.

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

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

Front-loads the core definition, then return shape, cross-tool relationships, and defaults before errors. Dense with no filler, though the return-shape sentence is long and could be tightened; it earns its length because no output schema exists.

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, the description carries the burden of explaining what comes back (page-ordered header/sections/footer with ids, headings, CTAs) and it does so fully, plus error strings and default resolution. An agent can invoke and interpret the response without further info.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond it: it explains the production-then-fallback resolution order for an omitted version and ties sequencePosition to save_page_content.sections[].sequencePosition. These semantics aren't in the schema, which only says 'Defaults to current production version.'

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 (structure of a landing page version) and enumerates the content returned: header, sections, footer, CTA placements, conversion goals. It also distinguishes itself from siblings by naming get_site and query_cta_performance 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?

Gives explicit routing: 'Use get_site for the saved HTML itself and version history' and links CTA text to query_cta_performance to explain when this tool is the right entry point. It also handles the omission/default case and the two failure conditions (version_not_found, page_structure_unavailable), so the agent knows when calling will fail.

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 read-only, idempotent, non-destructive, closed-world behavior, and the description adds genuinely new context beyond that: no siteId is required, results are aggregated per page with double-counted visitors relative to the dashboard's site overview, and the response is timezone-sensitive with timeZonePending indicating an in-progress zone switch. The aggregation caveat is exactly the kind of surprising behavior an agent would otherwise misinterpret.

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?

Well front-loaded: purpose, then usage triggers, then alternatives, then edge cases. The timezone paragraph largely restates the schema's timeZone description (IANA names, examples) and is the one section that could be trimmed, though it does add the timeZoneSource/timeZonePending return fields.

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, the description steps in to describe the return shape ('flat table-friendly summary with key metrics per page') and names the metadata fields the caller must interpret. Combined with the aggregation and timezone caveats, an agent has everything needed to call this correctly and read 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema for period (only 7d/30d/90d, long-term unavailable) and for timeZone (response-scoped, echoed back via timeZone/timeZoneSource, today's row is partial). It never mentions botFilter, so the schema carries that parameter alone.

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

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

States a specific verb and resource ('Get a performance overview of ALL landing pages at once') and enumerates the metrics returned (pageviews, visitors, CTA clicks, form submissions). It explicitly distinguishes itself from the page-scoped siblings get_analytics_summary and get_analytics_detail, so an agent can pick it without opening any schema.

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

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

Gives concrete triggers ('overall performance', 'how are my pages doing?') and names the alternative tools plus the condition that selects them ('For detailed analytics on a specific page, use get_analytics_summary or get_analytics_detail instead'). It also states a negative constraint: long-term periods are unavailable for the portfolio view.

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 carry the safety profile (idempotentHint=true, destructiveHint=false), and the description adds useful program behavior: friends start Free with no card, both sides get credit on first paid subscription. However, it never addresses why readOnlyHint=false for a 'get' tool (i.e., what side effect link generation may have), which is the one behavior an agent would want clarified.

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

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

Four short sentences, front-loaded with what the tool returns before explaining program terms and the quoting instruction. Slightly longer than strictly necessary for a no-arg call, but each sentence carries distinct information.

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

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

With no output schema, the description must cover the return, and it does call out the rewards field and its trial terms plus statistics. It leaves the link field itself and the shape of the statistics undocumented, so coverage is good but not exhaustive.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description instead spends its words on the response's rewards field, which is reasonable given no parameters exist.

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 ('Get your Convika referral link') plus the secondary payload ('your referral statistics'), which is enough to separate it from analytics/site tools. It does not, however, explicitly differentiate itself from other get_* siblings like get_site or get_domain_status beyond the unique resource name.

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 establishes clear context — this is for sharing a link with friends to earn credit — and explicitly cross-references create_claim_code as reporting the same trial terms, which helps an agent route between the two. There is no explicit when-not or exclusion statement.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world, so the description correctly spends its budget on non-obvious behavior: Pacific-time day boundaries, Google's 2-3 day fill-in latency causing recent days to grow, topQueries being truncated relative to totals, countsFrom/hasData semantics, and plan gating. There is no return schema, and these caveats are exactly what an agent would otherwise misreport.

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

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

Front-loaded with the selection rule, then a compact bullet list of return fields — efficient given there is no output schema. Minor waste exists: '180d, 365d, and all need Pro or MAX, as the other long periods do' restates the schema's plan note in an awkward clause.

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

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

Two-parameter, no-output-schema tool whose description fully covers return shape, unit conventions (ctr 0-1, position 1 is top), time zone, data latency, and the empty-data case. Nothing an agent needs to call and interpret the result correctly is missing.

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

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

Schema coverage is 100% and the parameter descriptions already cover period defaults and plan gating, so the baseline is 3. The description still adds real meaning: siteId is a page whose Search data is read at its Convika URL path, custom domains are excluded, and the period windows have latency caveats that affect interpretation.

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 (Google Search performance for one page): clicks, impressions, CTR, average position, and top queries. It explicitly separates itself from get_analytics_summary ('Not a page view or a visitor'), so an agent can choose between the two analytics tools 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?

Opens with an explicit when-to-use clause tied to user phrasing (including Japanese example queries like 「検索順位は？」), and closes with an explicit when-not ('Not a page view or a visitor in get_analytics_summary'). Plan prerequisites (180d/365d/all need Pro or MAX) and scope limits (custom domains not covered) are also 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real value on top: it discloses that the response carries version history with per-plan retention limits (Free 10 / Pro 50 / MAX 200) and the live URL. It does not cover auth requirements or failure behavior for an unknown siteId, so it falls short of a 5.

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

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

Front-loaded with the core purpose, then usage, then flow; every part is actionable. Minor redundancy between 'saved versions, published URL' in sentence one and 'version history ... and the live URL' in sentence three, but it is not costly.

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, the description responsibly summarizes return contents and retention limits, and the workflow line gives enough context to call it correctly. The remaining gap is the unresolved site/page ID ambiguity, which an agent may stumble on when choosing an ID.

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?

Single parameter at 100% schema coverage, so the schema carries the definition and the baseline is 3. The description adds nothing about the siteId, and notably does not resolve the site-vs-page terminology mismatch (tool name get_site, title 'Get page details', param siteId described as 'the ID of the page'), which is the one place description help would matter.

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 (get) and resource (Convika page) and enumerates the payload: saved versions, published URL, current status. Clearly distinguishable from list_sites/list_pages and from mutators like save_page_content or publish_site.

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

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

Explicitly states when to call it ('before editing or publishing to understand the page's current state') and then spells out the full workflow list_sites → get_site → save_page_content → create_preview → approval → publish_site, naming the alternatives and their order.

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

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

Goes well beyond the annotations by disclosing degradation behavior: a count that couldn't be read is null rather than 0, and 'stopped: true' means the workspace exceeded its page view cap so only pages and waiting are read. That is exactly the kind of edge-case context an agent needs to interpret results correctly, which annotations cannot convey.

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

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

Front-loaded with the trigger condition before the return details, and every sentence carries information. It is slightly dense with inline example utterances and a dash-lead host note, but nothing is genuinely wasted.

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

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

With no output schema, the description carries the full burden of explaining return values and does so field by field, including the null-vs-zero and stopped-state semantics. An agent can interpret the response without any other source.

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

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

Schema description coverage is 100% and the host parameter is already fully documented there; the description's line about host ('one site... without it, every site') largely restates it. No additional format or validation meaning is added, so baseline 3 applies.

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

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

States a specific verb and resource ('Returns each site's counts: pages, live pages, visitors30d, aiReads30d, entries30d') and enumerates exactly what is included, so an agent can distinguish it from get_analytics_summary or get_site without opening a schema.

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

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

Opens with an explicit trigger ('when the user asks how a site is doing, or how many people are waiting') including quoted example utterances, and closes with a clear exclusion routing content questions to get_form_submissions and get_orders.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds non-obvious behavioral content: the result set includes stale/frozen routes left behind after handover, which an agent would not infer from the schema or annotations and which matters when deciding to disable or replace paths.

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

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

Two sentences, zero filler: what is returned first, when to call it second. The most decision-relevant detail (frozen routes) is front-loaded rather than 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?

Annotation coverage, a 100%-described single param, and no output schema leave little unsaid; the description covers trigger and result scope. It could still mention whether the domain must be verified/active before listing, and roughly what a route entry contains, but nothing critical is missing for correct invocation.

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

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

With a single required parameter and 100% schema coverage, the schema already documents domainId and even points to get_domain_status and activate_domain_handover as sources. The description adds no additional syntax, format, or constraint information beyond that, so the baseline applies.

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

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

States a specific verb+resource (list routes under a custom domain) and immediately scopes it further by noting it includes frozen continuity routes left after handover. That detail separates it cleanly from the mutating siblings disable_domain_route and enable_domain_route, 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?

"Use after activate_domain_handover when the user wants to inspect, disable, or replace existing paths" gives a clear triggering context and hints at the follow-on tools. It stops short of naming when not to use it (e.g. a domain without handover), so it is strong but not fully exhaustive.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds value beyond that by framing it as a read-before-write step preceding set_goals, though it says nothing about result ordering, empty states, or limits.

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

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

Two short sentences with the action front-loaded and the usage guidance immediately after; no filler or 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 single-parameter read tool with rich annotations and no output schema, the definition covers purpose and workflow adequately. Only minor gaps remain around what the returned goal list looks like or how an empty configuration is reported.

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

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

With a single parameter at 100% schema coverage, the schema fully documents siteId. The description's phrase 'for a landing page' merely echoes that, adding no new syntax, format, or constraint detail.

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 (List) and resource (conversion goals configured for a landing page), which is distinct from siblings like set_goals or list_pages. An agent can immediately tell what this retrieves without opening the schema.

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

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

Gives three explicit triggering conditions (user asks about goals, checking what's tracked as conversions, and pre-reading before set_goals) plus the named alternative it pairs with. This is close to ideal when/when-not guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's job is to add behavior — and it does: result ordering ('top-level paths first and then by path'), the short-row shape, the three access values with a gloss for private_link, and full pagination semantics including the ~6,000-token reply budget, total, hasMore, and nextCursor reuse. This is context an agent could not derive from 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?

Usage is correctly front-loaded, and the per-parameter bullets make scanning easy. Some sentences do not earn their place: the multilingual keyword parenthetical, the closing 'Read-only.' that merely repeats the annotation, and the cryptic rule 'Link a public page only from a page anyone can read.'

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?

Filters, pagination, ordering, result row shape, and the no-page-means-create handoff are all covered, and an output schema exists so return data need not be explained at length. For a five-parameter read tool with full annotation coverage, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so 3 is the floor, but the description goes beyond it: it explains that omitting host dedupes pages to the site of their main URL, and gives the trailing-slash distinction for pathPrefix ('/guides/' lists under /guides/; '/guides' also includes /guides itself). The limit/token interaction and the cursor loop are also stated operationally rather than restated.

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

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

The opening sentence pins down the verb, resource, and the retrieval axis ('the workspace's pages by URL'), and the second sentence spells out exactly what is returned (id/siteId, name, path, status, url, access) plus result ordering. An agent can tell this apart from list_sites, get_page_structure, and create_page without opening any schema.

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

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

It gives concrete triggering scenarios ('every page under /guides/', 'pages on www.example.com', 'the ones not live yet') and explicitly routes the create case to create_page ('A path that isn't listed has no page: create_page makes one there'). It never explains why to prefer this over siblings like get_page_structure or list_sites, so the exclusion side of the guidance is incomplete.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value by enumerating the returned fields (id, name, subdomain, locale, status draft/published, public URL) and positioning the tool as the prerequisite for obtaining a siteId. It stops short of describing pagination or how limit affects results.

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

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

Three tight sentences: what it returns, when to call it, what comes back. The usage trigger is front-loaded right after the purpose, and no sentence 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?

With no output schema, the field enumeration in the description is exactly what an agent needs to know what it will receive. The remaining gap is differentiation from list_pages/get_site and any hint about result volume, which matters for a list 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?

The single `limit` parameter is fully documented in the schema (100% coverage), so the baseline of 3 applies. The description adds nothing about default page size or whether results are truncated, which is the one place it could have supplemented 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?

The description names a specific verb and resource ('List all landing pages ... owned by the user on Convika'), which is clearer than the bare name list_sites. However, it never addresses the obvious ambiguity with the sibling tools list_pages and get_site — the 'sites vs pages' terminology overlap is left for the agent to resolve.

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

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

It gives concrete activation contexts: 'When the user asks about their existing pages, wants to edit or check a page, or you need a siteId for any operation, call this tool first.' That is a strong positive trigger, but there is no exclusion clause telling the agent when to prefer list_pages or get_site instead.

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

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

Goes well beyond the annotations: it discloses what is preserved (content, versions, forms, goals, numbers), the collision outcome ('nothing moves and the answer says so'), the 301 redirect with redirectFrom naming, and the expectedBrandId guard returning brand_mismatch. These are exactly the side effects an agent cannot infer from destructiveHint/idempotentHint alone.

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

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

Front-loaded with the trigger, then behavior, then a sibling disambiguation — a logical order. It is on the long side, and the parenthetical keyword list '(ホームページ, Webサイト, ランディングページ)' is mild padding, but nearly every sentence carries actionable 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?

An output schema exists, yet the description still characterizes the response (workspace identity in brand.id/name/host, brand_mismatch) and covers collision, redirect, and preservation behavior. For a 3-parameter mutation tool, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: path character rules, the fact that '/' means the site's top page, and the redirect/brand-mismatch consequences of the parameters. It stops short of describing every edge case (e.g. max length of 200) but adds enough to beat the baseline.

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

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

States a specific verb and resource — 'Changes one page's path on the workspace's site' — and immediately illustrates with a concrete example (/cafe-guide to /guides/cafe). It also explicitly separates itself from set_site_url, so an agent can distinguish it from the closest sibling without opening either schema.

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

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

Opens with an explicit trigger condition ('when the user wants a page at a different path') plus multilingual example utterances, and names the alternative tool with the condition that selects it ('set_site_url puts a page at a full URL on a domain that isn't connected yet'). Both when-to-use and when-to-use-something-else are covered.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only the return payload ('pong'), which is useful but minimal; it says nothing about latency, timeout behavior, or whether the check touches external systems.

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 purpose front-loaded and no filler. Nothing could be removed 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 trivial zero-parameter diagnostic with no output schema, the description covers what the tool does and what it returns ('pong'), which is the key missing piece of structured information. Only the absence of any usage context keeps it from being fully 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?

The tool takes zero parameters, so the baseline of 4 applies. There is nothing for the description to clarify beyond confirming that no input is needed, which it implicitly does.

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 function ('health check tool') and its observable result ('returns pong'), which is enough to distinguish it from all sibling tools, none of which are connectivity checks. It is close to restating the name 'ping', but the addition of the expected response makes the behavior concrete.

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 an agent should call this versus any other tool, nor any preconditions or exclusions. For a diagnostic utility this is a notable gap, though the name itself implies the use case.

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

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

Goes well past the annotations (destructiveHint, openWorldHint) by spelling out that the real call changes what anyone on the internet sees, that dryRun publishes nothing, token expiry via expiresAt, plan headroom, per-page statuses, and error codes (confirm_token_required, confirm_token_invalid, pages_changed, brand_mismatch, limit_reached). The idempotencyKey guidance is consistent with idempotentHint=false, since retry safety requires an explicit key.

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

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

Front-loaded with the trigger and organized as a numbered two-step flow, which is the right structure for this tool. It is dense and mostly earns its length, but some parameter wording duplicates the schema nearly verbatim and the parenthetical keyword lists add clutter.

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

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

An output schema exists, yet the description still gives enough on statuses and summary counts for an agent to interpret results and retry correctly. With annotations covering the safety profile, nothing material is missing for a destructive, open-world batch publish.

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

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

Schema coverage is 100% and the schema descriptions already cover dryRun, confirmToken, idempotencyKey and expectedBrandId, so much of the description's parameter text is reinforcing rather than additive. It still adds genuine meaning the schema lacks: token lifetime and the pages_changed refusal rule, plus the per-status behavior of limit_reached.

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

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

States a specific verb and resource with scope ('publish several pages at once'), and contrasts itself with the sibling publish_site ('Like publish_site in production, the real call changes what anyone on the internet sees'). Real user utterances in Japanese and English make the intended trigger unmistakable.

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

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

Explicitly says when to use it (batch publish requests), that a dry run must precede the real call, and what to do when the token is refused (pages_changed: rerun the dry run). It also states the batching rule for larger jobs (several calls of up to 10 pages, each with its own dry run).

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

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

Goes well beyond the annotations (which only flag destructive/openWorld/not-idempotent) by explaining that preview is token-protected and does not touch the live version, that production makes the page publicly reachable at a specific URL resolution order, that hosting/CDN/SSL are handled, that IndexNow submission occurs on paid plans, and that the response carries a warnings array with preflight checks. It even guards against over-promising indexing outcomes.

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

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

Front-loaded with the core verb and slot choice, then bulleted for scannability, with the warnings-handling contract last. A couple of bullets (versionNumber default, slot description) duplicate the schema verbatim and could be trimmed, and the bilingual tagline adds no routing value.

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

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

No output schema, yet the description sketches the important part of the return (warnings with missing goals/meta/OGP/forms) and routes the agent to set_goals, save_page_content, and create_form to fix them. For a destructive, world-visible action, the preconditions an agent needs before calling are all present.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by expanding slot semantics (public URL resolution order, get_brand to find the workspace site) and by tying confirmProduction to an explicit user request. versionNumber and confirmProduction restate the schema rather than extend it, keeping this just below a 5.

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 ('Deploy a landing page') plus the two target slots, so the agent immediately knows this is a deployment action rather than authoring. It explicitly contrasts itself with create_preview for creation/editing, and the unspoken sibling publish_pages is at least distinguishable by singular scope.

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

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

Gives explicit routing rules: prefer create_preview for normal creation/editing so the user can review, use only when the user explicitly asks to publish/go live, and requires confirmProduction=true for production. Both the when and the when-not are stated, along with the guardrail parameter.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real operational context beyond them: scans count against the monthly analytics scan quota with overage billing, today's row is partial, and timeZonePending signals a pending workspace zone switch. It does not cover result ordering or pagination behavior, which keeps it short of a 5.

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

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

Front-loaded with the row shape and the use case before the operational caveats, and every paragraph carries information. The time-zone paragraph is long and partly duplicates the timeZone schema description, so it is dense rather than wasteful.

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, the description takes on the burden of describing the returned columns and the timeZone/timeZoneSource/timeZonePending fields, and it does so. For a 7-parameter read tool with full annotation coverage, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter constraints the schema lacks: dates must be valid calendar dates and startDate must be on or before endDate, plus the exact-text vs regex-href distinction between ctaText and ctaHrefPattern. The timeZone explanation largely restates the schema field, which caps it at 4.

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 ('CTA-level click analytics with daily time series') and enumerates the exact row shape (date, CTA text, link, type, clicks, unique clickers). It explicitly distinguishes itself from get_page_structure (placement) and query_timeseries (traffic context), so an agent can route without opening a schema.

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

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

Gives an explicit trigger ('Use when the user asks which buttons or links people click, or whether a CTA change worked') and names two alternatives with their distinct roles: get_page_structure for placement and query_timeseries for CTR context. Both the when and the when-else are covered.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial context beyond them: 3-month data window, bot/scanner exclusion, scan quota and overage billing, time-zone day semantics, partial-day handling, and timeZonePending 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?

The description is front-loaded and logically organized into purpose, data scope, date handling, and filter details. It is somewhat long and repeats some timeZone details already present in the schema, but every section contributes useful 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 tool with seven parameters, nested segment objects, and no output schema, the description covers the critical operational details: segment filter semantics, date/time-zone rules, data scope, and quota implications. It could be slightly more complete by mentioning the limit parameter, but the schema covers that adequately.

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 71%, so the schema carries most parameter meaning, but the description adds value: it clarifies date format constraints, startDate <= endDate, time-zone handling for whole days, supported segment filters (device, country), and provides a nested example. It does not explain the limit parameter, which is left 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?

The description immediately states a specific verb and resource: compare two visitor segments side-by-side with daily time series. It gives a concrete example and mentions the data scope, making it easy to distinguish from siblings like get_analytics_summary or query_timeseries.

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 explains how to define segments and gives examples, but never states when to use this tool instead of query_timeseries, get_analytics_summary, or get_analytics_detail. The overlap with get_analytics_summary is mentioned for data coverage, not as an alternative, so the usage guidance is implied rather than explicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description layers on genuine behavioral context: 3-month data window, bot/scanner exclusion, scan-quota and overage billing, visitors being non-additive across days, partial rows for today, and timeZonePending transitions. These are exactly the constraints an agent cannot get from 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?

Purpose and sibling routing are front-loaded, and the return-row shape and examples are well ordered. The timezone paragraph is long and packs several edge cases (timeZoneSource, timeZonePending, partial today) that could be tightened, but each sentence still 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?

No output schema exists, and the description compensates fully by describing each returned row field (date, dimensionValue, pageviews, visitors), the non-additive visitors caveat, and the timeZone/timeZoneSource/timeZonePending response fields. An agent has everything needed to call and interpret the 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?

Schema coverage is 100%, so the baseline is 3; the description earns above baseline by enumerating device values (mobile, desktop, tablet) and country codes (JP, US) that the schema does not list, explaining the 'all' dimensionValue, and detailing whole-day/timezone semantics for startDate and endDate. The limit parameter is left entirely to the schema, which keeps it from a 5.

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 (daily pageviews and unique visitors for one landing page) plus the exact optional dimensions and filters. It explicitly names the sibling tools it is not (get_analytics_summary, get_analytics_detail) and the distinction is clear without opening a schema.

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

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

Gives explicit when-to-use triggers ('how traffic moved day by day', 'which device, country, or source drove a change'), names the alternatives for overview and period-over-period comparison, and closes with four concrete invocation examples. Nothing about tool selection is left to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the bar is lower. The description adds real value the annotations cannot: exactly what is destroyed (answers, brand-mention flags, cited links, history), that it is unrecoverable, that re-adding the same text starts with no results, and that checks already consumed aren't refunded. However, it does not mention required auth/permissions, rate limits, or batch-failure behavior (partial vs all-or-nothing when some prompts are invalid).

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

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

Front-loaded with the trigger sentence, followed by a compact bullet list of edge cases; the Japanese examples earn their space by disambiguating intent. It is on the long side for a delete tool and a few clauses (e.g., the host bullet) repeat schema wording, keeping it shy of a 5.

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

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

No output schema exists, and the description covers it: it explains the return shape (removed/kept changes plus the saved state, like get_answer_check_results with no filter). Combined with idempotency and destructiveness annotations, the calling contract is clear; only auth/permission expectations are missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns +1 by tying parameters to outcome semantics: prompts by id (from get_answer_check_results' prompts) or exact text, host scoping, and expectedBrandId producing brand_mismatch on workspace switch. It also supplies error codes (not_saved, ambiguous_prompt, brand_mismatch) that are not in the schema, though several phrases (id-or-text, host description) largely restate the schema text.

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

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

States a specific verb (delete) and resource (saved questions of the workspace's AI answer check) immediately, and explicitly distinguishes itself from get_answer_check_results (source of ids) and update_answer_check_prompts (add/rename). An agent can route between the three siblings 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?

Front-loads a when-to-use trigger with multilingual example utterances, then gives concrete exclusions and alternatives: to change wording, delete here and re-add via update_answer_check_prompts; to disambiguate, send the id or host. It even adds a human-in-the-loop rule (ask before deleting a question with results).

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 say destructive/openWorld/non-idempotent; the description goes well beyond that by spelling out exactly what breaks (every page URL 404s immediately, HTTPS cert released), what survives (pages remain at their {name}.convika.page paths), and the main-URL fallback behavior, including that some pages only update on next publish.

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

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

Front-loaded trigger sentence, then effects, then a 'Before calling it' checklist, then the alternative — a well-structured progression. It is longer than strictly needed (the parenthetical Japanese trigger list and the repeated domain examples add bulk), but each block carries distinct 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?

There is no output schema, and the description compensates by noting the result lists stoppedUrls. Combined with consequences, prerequisites, and the sibling alternative, an agent has everything needed to invoke this destructive tool safely.

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

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

Schema coverage is 100% and the single 'domain' parameter already documents that it accepts an id or hostname such as www.example.com. The description adds scope ('one connected site' from this workspace) but no new syntax or format guidance, so baseline 3 applies.

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

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

States a specific verb and resource ('remove or disconnect a custom domain ... from Convika'), scopes it to one connected site, and lists multilingual user phrasings that map to the intent. It also distinguishes itself from the sibling disable_domain_route by naming it 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?

Gives explicit preconditions (call list_domain_routes and surface the affected URLs, obtain explicit user confirmation, warn about the root domain's A record) plus a clear routing rule: use disable_domain_route to stop a single path instead. Nothing about when/when-not is left to inference.

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

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

Annotations already declare destructive=true, readOnly=false, and openWorld=true. The description adds meaningful context beyond annotations: instant effect, production-only scope, and plan-based version retention limits. It doesn't cover reversibility of the rollback or auth requirements, but the added value is substantial.

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 action, then provides usage guidance and bulleted constraints. Every sentence earns its place; no redundancy or filler.

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

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

Given annotations already cover safety (destructive, openWorld) and schema covers parameters fully, the description completes the picture with when-to-use, prerequisites, and retention limits. No output schema means return values need not be explained, and nothing essential is missing.

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

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

Schema already documents siteId and versionNumber at 100% coverage. The description adds crucial meaning: versions beyond retention limits (Free: 10, Pro: 50, MAX: 200) are pruned and unavailable, directly informing the valid range and availability of versionNumber. This goes beyond schema constraints.

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 (revert/rollback) and resource (live landing page version), clearly distinguishing it from siblings like publish_site, save_page_content, or update_site. An agent can identify the tool's function immediately.

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

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

Explicitly says when to use it ('undo a recent change or restore an earlier version') and gives a prerequisite ('Call get_site first'). Also notes it only affects the production slot and lists retention limits. No explicit when-not or named alternatives beyond get_site, but the context is strong.

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?

Beyond the annotations, it discloses a lot: cost accounting (q × e checks taken up front from monthly quota, then purchased packs oldest first), refunds for errored or empty answers, a one-run-per-workspace concurrency limit, latency of up to ~12 minutes, and the meaning of each error code. It also explains idempotency-key retry semantics, which the annotations' idempotentHint=false would otherwise leave unclear. This is exactly the context that annotations cannot carry.

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 trigger phrases and cost rule are front-loaded well, but the paragraph is dense and over-long: billing, refunds, error codes, and idempotency all run together in one block. Some sentences duplicate the schema text ('leave it out for all four'), which does not earn 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?

There is no output schema, so the description must explain returns, and it does: the run object with answers, fromIncluded, fromPacks, repeated, plus the remaining balance. Error states and the pre-run confirmation requirement are all covered, so an agent can call this correctly without further inference.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-tool provenance for promptIds (the ids from get_answer_check_results' prompts) and the brand_mismatch consequence for expectedBrandId. It loses a point because the engines and promptIds default wording largely restates the schema descriptions verbatim.

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

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

States a specific verb and resource: it asks the workspace's saved questions on ChatGPT, Perplexity, Gemini and Google AI Overviews. It is clearly distinguished from the sibling tools it could be confused with, get_answer_check_results (reads answers later) and update_answer_check_prompts (saves questions first).

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

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

It gives explicit trigger phrases, including the Japanese ones, and states when to call it versus when to read results later, and it warns against calling it again to wait for answers. It also names the prerequisite siblings: update_answer_check_prompts for saving questions, and get_answer_check_results for the prompts and balance.

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 say readOnly=false, idempotent=false, destructive=false; the description goes well beyond them by explaining that every call appends a version (why it is not idempotent), that plan quotas (Free 10 / Pro 50 / MAX 200 / Enterprise unlimited) cause the oldest version to be permanently deleted with no rollback, and that the live and preview versions are never pruned. This nuance actually reconciles the destructive=false hint rather than contradicting it, since the served page is never destroyed.

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

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

Front-loaded with purpose and preview semantics, then organized under clear headers (Version history, Workflow, HTML guidelines). It is on the long side and carries some low-value ballast — the Japanese tagline 'ページ内容の保存・更新・デザイン変更。' and the niche form-page workflow — but every other line is actionable.

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

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

For a 10-parameter mutation tool with nested objects and no output schema, the description covers everything an agent needs: version quota and pruning consequences, why nothing is visible until create_preview, HTML document requirements (doctype, Tailwind CDN, <section> wrapping), and the data-cta tracking requirement for conversion goals. Nothing material is left unstated.

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

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

Schema coverage is 100%, so the schema already documents js, css, sections, patterns, designOverrides, etc.; most of the description's parameter notes (css only for non-Tailwind styles, js Pro+, sections need description ≥20 chars and 0-indexed sequencePosition) repeat the schema verbatim. The only genuine addition is tying 'sections' to the actual <section> tags and the backward-compatibility preference for sections over patterns, which is marginal. Baseline 3 is appropriate.

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

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

Opens with a specific verb + resource + object: 'Save a new version of a Convika landing page's HTML.' It also immediately distinguishes itself from siblings by stating that the live page and preview link do not change until create_preview/publish_site are called, so an agent can separate this from create_preview, publish_site, and create_landing_page without opening any schema.

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

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

Gives an explicit ordering (create_site → save_page_content → create_preview), an explicit gate for the risky sibling ('Use publish_site only after explicit user approval to go live'), and a separate branch for form pages (create_landing_page_preview → create_form → save_page_content → create_preview). When-to-use and when-not-to-use are both spelled out.

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

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

The annotations declare destructiveHint=false, but the description states 'Calling this replaces all existing goals for the page,' which is a destructive overwrite of existing goal configuration. This is a direct contradiction with the annotation, even though the description otherwise provides useful behavioral context about conversion calculation and tracking.

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 front-loaded with purpose and usage rules, then uses examples to clarify goal selection. It is somewhat long but well-structured, and the examples and replacement warning earn their 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 two-parameter mutation tool with a rich input schema and no output schema, the description covers purpose, prerequisites, goal-type selection, and replacement behavior. The main gap is the annotation contradiction and the absence of an explicit alternative such as list_goals for reading existing goals.

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

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

Schema coverage is 100%, so the schema already documents both parameters and nested goal fields. The description adds value by giving concrete examples that map user utterances to goalType and label values, and by explaining when to choose form_submission versus cta_click.

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: set conversion goals for a landing page. It defines what a goal is and clarifies that multiple goals can be set per page, making the tool's purpose immediately clear.

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

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

Explicitly says to call this after create_site when the page purpose is clear, and gives concrete rules for when to include form_submission versus cta_click based on user intent. It also warns that calling it replaces all existing goals, which is critical 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 only cover the safety profile (non-read-only, idempotent, non-destructive); the description adds substantial undisclosed behavior: returned CNAME/TXT records for new sites, 301 root redirect semantics, path-level idempotency of already-connected sites, stable TXT values across calls, and multi-workspace claim/handover states. It also discloses a consequence the annotations do not (guidance.existingSite means connecting would replace a whole site) and instructs the agent to warn the user first.

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

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

The first two sentences front-load what the tool does and when to prefer it, and the bullets are each tied to an actionable condition rather than filler. It is long (ten bullets) and a few edge cases (pending claim by another workspace) read as documentation detail rather than selection guidance, costing a point.

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

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

There is no output schema, and the description compensates by naming the response fields the agent must branch on (guidance.rootRedirect, guidance.rootNotServed, guidance.existingSite) and the follow-up tool. For a DNS-affecting mutation with cross-workspace edge cases, nothing needed to call or interpret it correctly is missing.

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

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

Schema coverage is 100%, so all three parameters are already documented, including makePrimary's deferred-primary behavior on unconnected domains. The description goes beyond the schema with route semantics — '/lp2' and '/lp2/' normalize to the same route but '/lp2/thanks' is distinct — which is meaningful invocation-relevant behavior rather than restatement.

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: 'Assign a full URL to a Convika landing page, including custom-domain paths', with two concrete URL examples. It also names the sibling it should not be confused with (setup_custom_domain) and the condition that separates them, so the agent can route without opening schemas.

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

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

Explicit when-to-use ('when the user asks to create, move, preview, or publish a page at a specific URL'), an explicit alternative with a discriminator ('Prefer this over setup_custom_domain when a path is included'), and a follow-up step ('After this tool succeeds, use create_preview'). Branch-specific guidance is also given for error codes and blocked scenarios.

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