create_page

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

No annotations are provided, so the description must carry the behavioral details. It discloses that it uses the WebSocket API, returns the page creation URL without opening a browser, and mentions the createActually flag behavior. It doesn't address error handling, idempotency, or permissions, which are relevant for a write operation. Overall, it provides some behavioral insight but leaves gaps.

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 description is three sentences and front-loaded with the core action and outcome. It packs essential information about return behavior and defaults without redundancy. Every sentence adds value; no fluff.

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 5 parameters, no output schema, and no annotations, the description covers the key aspects: creation, default project, body format, and the createActually flag. It does not mention what happens if the page already exists or error conditions, but for a straightforward create tool that's acceptable. The description is complete enough for typical agent use, with the main gaps being edge cases.

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 100%, so each parameter already has a description. The description adds a useful note about not duplicating the title in the body ('Avoid duplicating the title in the body since it's automatically displayed at the top') and clarifies the default behavior for format and projectName. This exceeds what the schema states, but not significantly, so a baseline of 3 is appropriate.

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 a new page in Scrapbox project on cosense (scrapbox).' It specifies the verb 'create' and the resource 'new page', and distinguishes itself from siblings like search_pages, get_page, and edit_lines by focusing on creation. The phrase 'returns the page creation URL without opening browser' adds clarity on the outcome.

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 mentions the default project behavior ('Uses my-cosense-project as default if projectName is not specified') and the body format options, giving context for usage. However, it does not explicitly state when to use this tool over siblings (e.g., when to prefer create_page vs edit_lines), though the create-vs-edit distinction is implicit. No exclusions or when-not-to-use guidance is given, but for a creation tool, this is adequate.

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