notebook

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

Adds substantial context beyond the annotations: write replaces and creates-if-needed, append adds at the end, delete is permanent-by-implication but pages never expire or change on their own, plus hard limits (50 pages, 20000 chars). The read-before-rewrite warning mitigates the destructiveHint=true profile rather than contradicting it.

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 with purpose, then a compact action glossary, then guardrails and limits — dense and useful throughout. Minor waste: the action list largely duplicates the action enum description verbatim, and 'Returns { data }' is thin.

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 4-parameter mutation tool with no output schema, the description covers lifecycle, capacity, and safety guidance well. The return value is only gestured at as '{ data }', leaving the agent to infer the response shape after list/read.

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 already 100%, so the baseline is 3; the description earns above that by spelling out action semantics that go beyond the enum labels — 'write replaces a whole page, creating it if needed' and 'append adds a line at the end.' It does not address the namespace parameter, which is left entirely to the schema.

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 resource ('named pages you read and rewrite yourself') and its intended content ('running notes such as progress on a long task'), then enumerates every action in one sentence. This is clearly a self-managed notebook, distinguishable from sibling memory tools like remember/recall/keep_moment.

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?

Gives explicit operating discipline: 'Read a page before you rewrite it' and 'delete one when it is done.' The line 'Pages are never recalled automatically' implicitly positions it against auto-surfacing memory tools, but no sibling is named as an explicit alternative, so this stops short of full when/when-not routing.

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