notion_add_tabs

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

No annotations are provided, so the description carries the full burden. It usefully discloses that page_id may be any block supporting children, that position defaults to 'end', and the exact tab object shape, but says nothing about permission requirements, what happens with an invalid block ID or malformed JSON, or whether existing page content is affected.

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 one-line purpose followed by a tight param list with a compact example; no sentence is filler and the example JSON substitutes for paragraphs of prose.

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?

With an output schema present, return values need not be described, and the parameter contract is complete. However, for an unannotated write tool the description should say something about permissions, failure modes, or interaction with existing page content; those gaps leave it adequate but not complete.

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 0%, yet the description fully compensates: it explains the page_id semantics (page or any child-supporting block), gives a concrete JSON example for tabs_json with required/optional fields spelled out, and enumerates position's three accepted forms including the default.

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 ('Add') plus a precisely defined resource ('a tab block (a row of tabs, each with its own content)'), so an agent knows exactly what will be created. It does not differentiate itself from content-insertion siblings such as notion_append_content or notion_insert_page_content, which is the only thing keeping it from 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?

The description never says when to use this tool versus alternatives, nor any prerequisites or exclusions. Given siblings like notion_append_content, notion_insert_page_content, and notion_replace_page_content, an agent is left to infer that 'add tabs' is the choice when tabbed layout (not plain content) is needed.

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