learnings

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

No annotations exist, so the description carries the full burden. It discloses useful behavior — 'no args = list sites', notes may embed runnable act scripts, save replaces the local note, and the hedged trust level 'Hints, never rules'. It does not cover whether notes are shared/synced across sessions, permission needs, or what list output looks like.

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?

Tight single paragraph with no filler, front-loading the resource then the read/write protocol. Phrasing like 'fill {{placeholders}}' and 'via {domain, save}' is terse to the point of being slightly cryptic, but every sentence carries 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?

For a dual-mode (read/write) tool with three optional params and no output schema, the description covers the core read and save flows well. It omits the spaceId parameter and any indication of what a list-sites or note-fetch response contains, leaving a modest gap.

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 3 is the baseline, but the description adds semantics beyond the schema: calling with no arguments lists sites, and the save param must be merged with a prior get rather than blindly overwritten. The spaceId param is not addressed in the description.

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 states a specific resource — persistent site notes (APIs, walls, pitfalls) — and distinguishes its read mode (call with domain, no args lists sites) from its write mode (save). It is clear what the tool is for, though it never names itself as the memory/notes sibling versus the other browser tools explicitly.

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 clear when-to-use context: call before first acting on a site, run embedded ```act scripts instead of rediscovering, and save a note back after learning something non-obvious. No explicit exclusions or named alternatives, but the trigger conditions are concrete.

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