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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds genuine context beyond that: the bracketed [widgets:read] scope tags disclose the auth requirement for each read, and 'with current revision' hints at revision semantics. It stops short of explaining what 'current revision' means relative to the 'draft' query, which is the one behavioral nuance an agent would need.

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?

The summary sentence is front-loaded and the per-query bullets are scannable in a way prose would not be. The repetition of the literal phrase 'Read widget' on all eight lines is redundant padding that a more compact mapping would avoid.

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 values need no explanation, and annotations cover safety. The description covers the full query surface, which is the main complexity of this single-parameter polymorphic tool. The remaining gap is pagination guidance — limit/cursor and how they interact with resultCursor — which the description never mentions despite this being a list-capable read.

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 0% and the query values appear in the schema only as bare consts, so the description carries real weight by mapping each query value to the data it returns. widgetId, limit, and cursor remain undocumented in prose, though their types and defaults (limit default 50, max 200; cursor default "start") make them inferable from 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 opening sentence gives a specific verb (Read) and names exactly what is read: widget configuration, forms, installation details, plus a 'current revision' qualifier. The bulleted query enumeration removes any ambiguity about scope, and the sibling tools (content_search, conversations, knowledge) are clearly different resources, so no differentiation problem exists.

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 bullet list effectively serves as selection guidance: an agent knows to use query="fields" for fields, query="draft" for the draft, query="installation" for installation data. What is missing is any exclusion or prerequisite guidance — nothing says when NOT to use this tool, nor whether reading a draft requires specific permissions or an unpublished widget state.

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