Append a user-facing comment to a document without changing its searchable content. Use for annotations or feedback.
Append a user-facing note (comment/annotation) to a document. Notes are separate from the document's searchable 'content' field — to change body text or other metadata fields, use update_document instead.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The document ID | |
| note | Yes | The note text to add |
Changes observed during successful MCP inspections.
v3.2.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey readOnlyHint=false and destructiveHint=false, and the description is consistent with both. It adds genuine value beyond annotations by clarifying behavioral scope: the note is a separate user-facing annotation that does not touch the document's searchable content field, preventing misuse (e.g., treating the note as body text). It doesn't discuss return values or repeated-append semantics, but for a simple additive operation the safety profile is well covered.
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?
Two sentences with zero filler. The first states the core action; the second adds scope clarification and alternative routing. Every word earns its place, and the action verb is front-loaded rather than buried.
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-param tool with full schema coverage and no enums, nested objects, or output schema, the description covers the action, the boundary between notes and content, and the correct alternative. A small gap remains: it never describes what a successful call returns (no output schema exists), and it doesn't mention the related note-management siblings (list_document_notes, delete_document_note), but neither is essential for making a correct call.
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% — both id ('The document ID') and note ('The note text to add') are already documented in the input schema. The description maps those roles (document id, note text) but adds no detail beyond what the schema provides, so the baseline 3 applies.
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 uses a specific verb + resource pair ('Append a user-facing note (comment/annotation) to a document') and explicitly distinguishes itself from update_document by stating that notes are separate from the searchable 'content' field. An agent can tell this tool apart from the many document-related siblings without needing to inspect schemas.
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 description gives explicit routing guidance: it states what this tool is for (adding a user-facing note) and when it should NOT be used ('to change body text or other metadata fields'), naming update_document as the alternative. This is exactly the when/when-not/alternatives pattern the rubric rewards.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.