add_pages

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

With no annotations, the description carries the full burden, and it does disclose genuine behavior: the operation copies the notebook, inserts pages at the end or after a 1-based index, and describes the rendering outcomes in detail. However, it never clarifies whether 'path' is the source or the destination copy, whether the original is preserved, whether the call is repeatable, or what is returned — material gaps for a write-style tool with 13 parameters.

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 purpose is helpfully front-loaded in sentence one, but the body is an unstructured ~500-word wall that mixes a markdown DSL manual, an SVG drawing tutorial, and parameter docs into one paragraph. The long SVG section and formatting arcana belong in a reference doc or example_pages, not inline; an agent must scan the whole block to find the two or three sentences that constrain correct invocation.

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 rendering-heavy tool the description is unusually rich on the output-authoring side, and with no output schema it rightly spends its budget on what the pages will look like. But the operational essentials an agent needs before calling — what 'path' means, where the copy lands, what a successful response looks like, and what size/ink/open_in_noteful do — are absent, leaving a complete picture of formatting and an incomplete picture of the call itself.

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 0% and no enums are declared, so the description is the only source of parameter semantics — and it delivers real value, enumerating look values and their meaning, theme light/dark semantics, paper (dot|grid|ruled|blank), seven fonts, three hand styles, and two pens, plus after_page indexing. Gaps remain: 'size', 'ink', 'open_in_noteful', and the required 'path' are never explained, and the accent list (coral, amber, sky, purple, teal, pink) omits the declared default 'blue'.

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 gives a concrete compound verb and resource: copy a notebook and append/insert handwritten pages, with the placement rule (end, or after page N, 1-based) spelled out. That is enough to tell it apart from render_page or page_layout in practice, but the description never names a sibling or explicitly contrasts them, so it stops short of a 5.

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?

Usage is implied by the imperative phrasing rather than stated: an agent can infer 'use this to author new pages in a copy of a notebook'. The one explicit workflow cue is 'Read an example first: example_pages', which points at a sibling but only as a prerequisite, not as an alternative. There is no when-not-to-use guidance versus design_page, write_on_page, or design_mockup.

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