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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real value beyond that: it says what comes back ('full title and full body') and explains the motivation ('search rows carry only a short preview'), plus explicitly denies side effects. It stops short of describing not-found/invalid-id behavior or the effect of the person/project act-as parameters.

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 sentences, front-loaded with the trigger condition, then the return payload, then the exclusions. Every clause carries distinct information and nothing is repeated for padding.

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 no output schema, the description usefully covers the return shape (full title and body), and the single required parameter is fully documented in the schema. Only minor gaps remain — no mention of behavior when the id is stale or unauthorized, and the act-as parameters are left entirely to the schema.

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 description coverage is 100% and the schema's own text already says the id comes from connections_notes_search and is 'Never a to-do's id.' The description restates the same provenance point, adding only the rationale that search returns previews; it says nothing about the person or project parameters. Baseline 3 applies when the schema is doing the documentation work.

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 (read/open) and resource (a note), and scopes it to 'the whole of a note they already have' that the agent has an id for. It is clearly separable from connections_notes_search (which returns previews) and connections_todo_list (a different resource).

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 an explicit trigger ('when the member asks to open, read or see the whole of a note') plus the precondition ('you have its id from connections_notes_search'). It also names when not to use it — searching, mutating, or opening a to-do — and routes the agent to connections_todo_list.

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