build_page

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

With only readOnlyHint=false available, the description carries the behavioral load well: dry_run defaults to true, validation errors block the real save, duplicates are refused with blocked:true plus an existing page_id, only 'custom' pages can be created repeatedly, and special types auto-enable their data sources (store→use_store, member→use_member, etc.). It also warns that omitting seo publishes an empty title/description.

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 action, then the dry_run workflow, then the edge-case constraints, so the agent gets the critical path first. Four dense sentences with little waste, though the uniqueness sentence packs several distinct rules together.

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 7-param nested-object create tool with no output schema, the description covers the safety flow, source format, type side effects, and conflict behavior. The only real gap is that the success return (e.g. the new page_id) is not described, though the failure path's page_id is.

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 cross-parameter meaning beyond the schema: source must take the shape { sections: [...] } built via new_section, and dry_run must be read as a two-phase flow rather than a simple flag. These additions go beyond the per-field 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+resource and an explicit scope differentiator: 'Create a brand-new page AND set its full content source in one step.' That 'one step' framing implicitly separates it from the sibling pair create_page/update_page_source. However, it never names those siblings, so an agent must still infer which of the many page-related tools to pick.

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 operational guidance: call dry_run=true first then false, build sections with new_section, and the uniqueness rules (one main/error/maintain page per site, unique slugs, duplicates refused and return the existing page_id to edit instead). It lacks explicit when-not guidance (e.g. 'use update_page_source to modify existing content'), but the create-vs-edit boundary is derivable from the duplicate rule.

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