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

With readOnlyHint/idempotentHint already covering safety, the description adds substantial operational behavior: large sections return jsonFragment that must be concatenated in cursor order and parsed only after nextCursor is null, a conflict means the record changed and fragments should be discarded, and a partial fragment is never a complete fix. It also discloses a privacy constraint (end-user personal data, quote minimally and mask identifiers).

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?

Front-loaded with the purpose, then ordered by reading flow, and every sentence carries operational weight (paging mechanics, conflict handling, privacy). It is a dense single block mixing several concerns, which costs a little readability but no sentence is filler.

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?

An output schema exists, so return-value explanation is not required; the description covers everything else an agent needs — section choice, pagination protocol, conflict recovery, the no-write guarantee, and the data-handling constraint. Nothing necessary to invoke it correctly is missing.

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 67% and the section enum has no inline descriptions, but the description richly explains each section's payload (overview/change/evidence) and clarifies cursor semantics for fragment assembly and paging. It does not add meaning for reason, user_intent, or the two UUIDs beyond the schema, so it stops short of full compensation.

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 and resource ("Inspect a saved MCP recommendation") with singular scope, which inherently separates it from the list_mcp_recommendations and get_mcp_overview siblings. An agent immediately knows this reads one saved recommendation record.

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 reading order (overview first for rationale/confidence/scope, then change for before/after, then evidence for retained calls/contract/drift), plus the rule to keep the same recommendation and section while paging. It also states the when-not: this read tool does not apply changes, and you must check the repo contract against the saved base first.

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