note_bodies

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

Goes well past the readOnlyHint annotations: discloses the hard cap of 50 ids, that unknown ids are silently skipped (a real failure-mode detail), the return shape, and the Automation-access requirement for Notes. That is precisely the context annotations cannot carry.

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?

Four tight clauses, no filler. The core action is front-loaded, and the operational caveats (cap, silent skip, permissions, id source) follow in descending order of importance.

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?

An output schema exists so return values need not be described, yet the description still sketches the [{id, body}] payload; combined with the cap, skip behavior, and auth requirement, an agent has everything needed to call this correctly on the first try.

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 0% for the single 'ids' parameter, so the description must compensate — and it does, establishing the max of 50, the silent-skip behavior for unrecognized ids, and the upstream source of valid ids. It stops short of stating format/syntax of an individual id, keeping it at 4.

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 ('hydrate plaintext bodies for note ids') and immediately distinguishes itself from the pointer-only siblings notes / notes_all. An agent can tell exactly what it gets back (plaintext bodies) versus what the list tools return.

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?

Explicitly names where the ids come from ('Get ids from notes / notes_all') and frames the tool as an opt-in second step after pointer-only search. It does not spell out a when-not-to-use case, but the two-step workflow is unambiguous.

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