Page Templates

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

Annotations declare readOnlyHint=false, openWorldHint=true and destructiveHint=false; the description usefully augments this by stating preview 'writes nothing' and that render can be reversed via notion_undo. It also implicitly flags mutation (create/append) and that render uploads charts and places live views, which are real side effects. Return formats and error behavior are not disclosed, but the safety-relevant behavior is well covered.

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 is front-loaded, but the remainder is one enormous run-on paragraph with nested parentheticals that buries the per-action guidance mid-sentence. The length is arguably justified by the DSL complexity and every clause conveys something, yet the lack of structure (no separation of actions vs. template spec) hurts scanability.

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 nine-action, deeply nested tool with no output schema, the description is substantively complete: it covers every action, built-in templates, the template object shape, variable syntax, and all node types. Only the return values of list/export/import and error handling are left unspecified, which is a minor gap given the richness elsewhere.

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 78%, so the schema documents most params (name, parent, append_to, compare_to). The description goes well beyond it by defining the free-form `template` spec, the `variables` interpolation syntax, `slots`, and the full node DSL, which the schema cannot express. That is meaningful added semantics for the two most complex, free-form parameters.

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+resource+benefit ('Build pages from reusable templates instead of many block calls'), distinguishing this tool from siblings like notion_insert_blocks and notion_create_page. It then enumerates all nine actions and the four built-in templates, so an agent can tell exactly what the tool does and when it replaces lower-level block calls.

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?

Per-action conditions are given inline: validate checks a template and compiles variables, preview 'writes nothing', render targets `parent` or `append_to`, and delete/export/import are self-evident. The routing away from 'many block calls' is explicit, but it never names a specific sibling alternative (e.g. notion_list_templates or notion_create_page) to prefer for a given case, so it stops short of full when-not guidance.

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