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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds valuable context by noting the content is curated from advisers and scheme rules and is guidance rather than authoritative plan terms. This helps the agent understand the nature and reliability of the information without contradicting the annotations.

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 description is a single sentence with no filler, front-loading the core resource ('Curated notes from licensed advisers and the scheme rules') before listing examples. It could be slightly more structured, but it is appropriately concise and each word adds meaning.

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?

The tool is simple with three optional parameters and an output schema, so the description does not need to explain return values. However, it lacks explicit guidance on how to combine parameters or when to use this tool over siblings like plan_terms. The negative statement about plan terms helps, but the context is still somewhat thin for an agent facing many sibling tools.

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%, so the description must compensate for parameter meaning. It provides some topic examples (underwriting, claims, tax) that relate to the 'topic' parameter, but does not explain the 'brand' or 'question' parameters at all. It also doesn't mention that the topic parameter is constrained by a regex pattern. The description only partially clarifies the parameter semantics, leaving significant gaps.

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 clearly states the tool provides curated adviser notes and scheme rules, covering specific domains like underwriting, claims, and tax. It explicitly contrasts itself with plan terms ('Guidance, not plan terms'), which distinguishes it from siblings such as plan_terms and search_plan_terms. An agent can easily understand what this tool is for.

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 description implies usage contexts by listing topics (underwriting, claims, switching, tax) and states it is 'guidance, not plan terms,' which hints at when not to use it. However, it never explicitly names alternative tools or provides clear when-to-use versus when-not-to-use guidance. The agent must infer selection criteria from the topic list and the negative statement.

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