Create landing page draft

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

Beyond the annotations it discloses that nothing goes live on create, that drafts count against the plan allowance, that the brand kit sets colours, and that a retry with the same idempotency_key replays the first answer rather than creating twice. The idempotentHint=false annotation is not contradicted because the description frames idempotency as conditional on the supplied key. It does not describe failure modes beyond publish-blocking checks.

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 are well front-loaded and the scope/publish gate comes before detail. But roughly two thirds of the text is a block-by-block tutorial that duplicates the blocks parameter description word for word, which is bulk the agent already has in the schema; those sentences do not earn their place in the tool description.

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 12-parameter mutation tool with no output schema, the description covers the return shape ("the page and the checks that still stop a publish"), the publish gate, idempotency/retry semantics, content-truthfulness constraints and the link/bracket syntax. An agent could call this correctly from the description plus schema without further discovery.

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 every parameter, and the long block-composition passage in the description (hero/layout avatar, links, social, countdown, location, booking, bracket rules) is reproduced nearly verbatim from the blocks parameter's own schema description, adding no meaning on top of it. The genuinely additive content — recommended page recipes for bio vs landing — is minimal. Baseline 3 is right.

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 two sentences state a specific verb and resource ("Creates a draft page") and immediately name the boundary with the sibling that publishes (postfjord_publish_page), so an agent can tell creation from publishing without opening a schema. The kind=bio vs kind=landing distinction is then spelled out with scope differences (one per workspace vs many per plan).

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 clear when-to-use context and routes to prerequisites: image ids come from postfjord_list_media, form ids from signup forms in postfjord_list_pages, retained block ids from postfjord_get_page, and publishing needs postfjord_publish_page plus the owner's yes. What is missing is an explicit exclusion — nothing says to use postfjord_update_page instead when the page already exists, despite that sibling being present.

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