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

Annotations already declare non-read-only, idempotent, open-world, non-destructive, so the bar is lower; the description still adds real substance by spelling out what gets captured (screenshot, title, favicon, fonts, tech stack), when the palette is extracted, the 50-URL batch cap, and that duplicates are skipped — the last concretely grounding idempotentHint=true. It stops short of saying what a save returns or what happens on partial failure.

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?

Three tight sentences, with the primary action and target library front-loaded, followed by capture behavior, then operational limits. Every clause carries information: no restatement of the tool name and no filler.

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 five-parameter write tool with no output schema, the description covers what is stored, the batch ceiling, dedup behavior and collection auto-creation — enough to call it correctly. Return shape and authentication requirements are unaddressed, so it is not fully 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 coverage is 100%, so 3 is the baseline, but the description adds a constraint not present in the schema — the 50-URL cap on a single call — and explains that the target collection is created when missing, which clarifies the collection/create_collection pair. The urls-vs-items alternative is still only explained by 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 verb and resource ('Save websites to the user's Moodmark library') plus an explicit scope modifier (optional collection). It's clear what the tool does, but it never contrasts itself with the closest sibling, update_bookmarks, so the agent must infer the boundary between saving new sites and updating existing bookmarks.

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?

Usage context is implied: 'optionally into a collection (created if missing)' and 'Up to 50 URLs per call' hint at how to batch. But there is no explicit when-to-use this vs update_bookmarks, and no guidance on when to pick the flat 'urls' form vs the per-site 'items' form beyond what the schema says.

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