Connect Notion show rundown

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

Annotations already indicate write behavior (readOnlyHint=false, openWorldHint=true) and non-destructiveness (destructiveHint=false). The description adds some value by enumerating scaffold contents (e.g., approval policy, token-safety notes), which suggests internal structure, but it does not disclose side effects, API dependencies, or how the scaffold is materialized beyond the annotation baseline.

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 entire description is a single, front-loaded sentence that immediately names the action and resource, followed by a compact list of key features. No filler, no repetition, and every clause adds information.

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 10 parameters, no output schema, and minimal annotations, the description is underspecified. It does not explain prerequisites (e.g., Notion API credentials), return values, failure modes, or how the scaffold integrates with other COMPs. The brief list of components is not enough to give an agent full operational context.

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 only 20%, with only 'name' and 'parent_path' described. The description names high-level components that map loosely to parameters (scene maps -> scene_count, property maps -> property_count, approval policy -> approval_required, adapter source -> adapter_mode), but it doesn't explain default values, allowed enums, or relationships. The agent must infer parameter meanings from defaults and names, which is insufficient for a 10-parameter tool.

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 description clearly states the action ('Create') and the resource ('Notion show-rundown scaffold') and lists specific components (scene maps, property maps, approval policy, adapter source, token-safety notes), making it distinguishable from generic 'connect' tools. However, it doesn't explicitly differentiate from related scaffold/creation tools in the sibling list, 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?

There is no guidance on when to use this tool versus sibling scaffold/connect tools. No alternatives, exclusions, or prerequisite context are provided. The description merely states what it does, leaving the agent to infer appropriate usage.

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