start_page_draft

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

With no annotations provided, the description carries the full burden, and it delivers: no network on start, disposable cache backend (Redis vs in-memory), sliding ~2h TTL, incremental persistence on commit, resumability on timeout, up-front refusal semantics for special page types, and side effects deferred to commit (SEO applied on commit, data-source enabled on commit). Failure modes and state transitions are fully disclosed.

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 text is dense and front-loaded, with the purpose and workflow in the first sentence and constraints in a clean second paragraph. However, ALL-CAPS emphasis ('INCREMENTALLY', 'DISPOSABLE', 'ONE page per site') reads as shouting and slightly hurts readability, and a few notions are repeated (no network / disposable cache). Every sentence carries value, but the formatting is not ideal.

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

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

The tool sits in a multi-step workflow, and the description fully orients the agent: it names the companion tools (add_draft_section, commit_page_draft), explains the cache lifecycle, covers refusal conditions for unique/special pages, specifies which page types need data-sources on commit, and handles the no-output-schema gap by describing behavior rather than return values. Nothing essential is missing for a correct invocation.

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

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

Schema coverage is 100%, yet the descriptions add substantial meaning beyond type definitions: the slug field explains leading-slash stripping, bare-path matching ('/cart' would 404), per-store-type slug requirements, and the homepage exemption; the type enum maps each special kind to its required data-source on commit; seo indicates it maps to settings.seo applied on commit. These are rich, decision-relevant semantics, well above 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?

The description opens with a precise verb and resource: 'Start a page draft (no network)'. It explicitly distinguishes itself from a sibling: 'Use this instead of build_page for large/multi-section pages', and frames a clear two-phase workflow ('cache each section with add_draft_section, then commit_page_draft persists it to the backend'). The purpose and place among the page-building tools is unambiguous.

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

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

The description names its alternative (build_page) with a concrete selection condition ('for large/multi-section pages'), gives step-by-step workflow guidance, prescribes failure recovery ('if a draft is ever lost, just re-send the sections, never a failure'), and states when the tool refuses with redirection ('the draft is refused up-front with the existing page_id to edit instead'). An agent knows exactly when and how to use it.

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