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

Annotations already flag readOnlyHint=false and destructiveHint=true, so the description is not the sole source of the write/destructive signal. But nothing in the text explains what exactly is destroyed or overwritten (does an existing session for that day get replaced?), what happens when only title or entry_id is supplied, or whether logging a session on a finished item resets status. An openWorldHint=true, non-idempotent write deserves at least a note on repeat-call behavior, which is absent.

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 short sentences, front-loaded with what is being recorded and followed immediately by concrete examples. No filler, no restating of the title, nothing that could be cut.

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 7-parameter, zero-required, destructive, non-idempotent mutation with no output schema, the description is too thin. It covers the day/hours/note trio well but is silent on the identifier parameters (entry_id, title, shelf, shelf_id), on what is returned, and on the destructive semantics that the annotations only hint at.

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 86% and every parameter carries its own inline description, so the baseline is 3 by rule. The description adds a little illustrative meaning through the sample note strings ('played Wingspan for two hours last night', 'session 12 of our campaign'), which conveys tone and expected granularity beyond the schema's terse field descriptions, but it adds nothing about the id-versus-title-versus-shelf resolution order.

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 verb-plus-resource is concrete ('log a session on a shelf entry' with a day, duration, and a note) and the example lines make the concept immediately graspable. It is not easily confused with sibling tools like add_to_shelf or update_progress, though the description never names a sibling to sharpen the contrast.

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?

Usage is implied by the domain (recording that an activity happened) and the note that logging a session on a wishlist item moves it to in-progress gives useful context on a side effect. However there is no explicit when-to-use versus keep_challenge, update_progress, or the bulk sibling, and no statement of prerequisites such as the entry needing to already exist on a shelf.

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