Comment on a session

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

Annotations already declare the write/append shape (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds a genuine unstated constraint: "Never include secrets," which matters precisely because the note is team-visible. It does not disclose that repeated calls create separate additive notes (idempotentHint=false) or that notes cannot be edited or removed, which would complete the picture.

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?

A single front-loaded sentence names the action, the audience, and the accepted content types, closing with the safety caveat. Nothing is redundant and nothing needs to be re-read.

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 simple two-parameter tool with full schema coverage and annotations covering the safety profile, the description supplies purpose, audience, and content constraints, so an agent can call it correctly. What is missing is edge behavior — whether the session must already be shared, and what happens on failure — though with no output schema this is a minor 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 100%, so both `id` and `body` (with minLength/maxLength and plain-text-or-Markdown guidance) are fully documented structurally. The description adds only the "short note" framing and the no-secrets content rule for `body`, which is a modest increment over 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?

The description states a specific verb and resource ("leave a short note on a shared session") and enumerates the note types (question, finding, picked-it-up), which clearly separates it from update_session or share_current_session. It stops short of naming any sibling explicitly, so the differentiation is inferential rather than stated.

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?

The examples given ("a question, a finding, or that you picked it up") communicate when an agent should reach for this tool rather than mutating the session. There are no explicit exclusions or named alternatives, so a borderline case like "I want to change session metadata" has to be inferred.

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