reading_annotate_passage

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

With annotations carrying only a title, the description carries most of the behavioral burden. It discloses that the operation writes an annotation, that the annotation is a Claude margin annotation rather than a user note, and that it is quote-anchored. It does not cover failure behavior, permissions, idempotency, or what the created annotation looks like, which are meaningful gaps for a mutation tool.

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, no filler: the first names the core operation and the second gives an important exclusion. The main information is front-loaded and every sentence earns its place.

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 an 8-parameter tool with no output schema, no annotation behavioral hints, and 0% schema coverage, the description leaves too much implicit. It gives the core intent and a boundary, but an agent still cannot confidently determine how to populate optional fields or what to expect after invocation.

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%, so the description must compensate for undocumented parameters. It implicitly explains quote and chunkId through 'anchored to a quote in a chunk,' and note via 'annotation,' but it says nothing about bookId, kind, mood, tags, or parentId. With eight parameters, this is insufficient.

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 opens with a specific verb and resource: 'Write a Claude margin annotation anchored to a quote in a chunk.' It clearly distinguishes this tool from human-note submission by declaring that human private notes should be created through the HTTP reader API, not this MCP tool.

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?

It gives an explicit when-not: human private notes should go to the HTTP reader API rather than this tool, and the quote/chunk anchoring tells the agent the intended target. It does not explicitly route to sibling tools like reading_reply_to_annotation for follow-up replies, so it stops short of full alternative guidance.

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