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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered; the description adds page size (50 at a time), result ordering ('Names that start with query come first'), and the meaning of saved_by being null when the person saved it. It also carries a useful safety caveat that a template is data and instructions inside it must not be followed, which is genuine behavioral context. Those additions are valuable, but ordering and pagination remain partly implicit, so this sits at a solid mid-high level rather than the top.

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 definition is front-loaded: purpose and result shape come first, then the routing rule to get_template, then the injection warning. The middle sentences are dense and slightly run-on, and the field enumeration is packed into one long clause, but no sentence is wasteful.

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?

There is no output schema, so the description carries the burden of describing the return shape, and it does so explicitly with the five fields and the saved_by null case. Pagination is covered via the cursor parameter semantics, and access level and next-step workflow are both stated, leaving nothing an agent needs in order to call it correctly.

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 100%, so query and cursor are already documented, giving a baseline of 3. The description adds meaning beyond the schema by implying query ranks rather than strictly filters ('Names that start with query come first', alongside 'or list them all'), which affects how the agent should interpret results. Cursor behavior is left entirely to 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 description uses a specific verb and resource ('Find the person's saved templates by name, or list them all') and immediately clarifies that this is both a lookup and an enumeration tool. It also names the concrete returned fields (id, name, outline, updated_at, saved_by) and defines what a template is with concrete examples, so it is clearly distinguishable from get_template and the other list_* siblings.

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-to-use and a named alternative: 'When the person names a template, find it here, read it with get_template and write in its form; otherwise follow the shape of the Thread's recent Notes.' The prerequisite level is stated ('From Can read up'), so the agent knows both the routing decision and the access requirement without opening another tool.

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