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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false; the description is fully consistent with these. It adds valuable behavioral context: tokenized matching behavior, the fact that bill titles often don't match, pagination semantics (limit/offset, has_more), text_mode character caps, and the corpus envelope being independent of contribution_type. This goes well beyond 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 lengthy but each sentence serves a purpose: usage scope, return metadata, drill-down, exclusions, pagination, alternatives, and authority. It is front-loaded with the key directive and structured with clear separations. Slight redundancy exists (e.g., 'USE THIS TOOL WHEN' restates the title), but overall it is well-organized and earns its length.

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?

Given 9 parameters, rich annotations, an output schema, and multiple related siblings, the description covers all critical contexts: when to use, when not to use, how to paginate, how to retrieve full text, what each contribution_type means, and the authoritative nature of the data. It also points to the workflow for member-specific queries. This is fully complete for the tool's complexity.

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%, but the description enriches the query parameter with practical guidance (e.g., 'Pass tokens that would appear in someone's speech', 'Bill titles often DON'T match'). It also clarifies member_id (integer ID, not name string, with explanation of the old field), text_mode, and contribution_type semantics. This is high-value elaboration beyond bare schema definitions.

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 opens with a specific directive: 'USE THIS TOOL WHEN searching Hansard by topic, bill title, or text phrase.' It clearly identifies the resource (Hansard debates) and the action (search), and distinguishes from sibling tools by contrasting with parliament_get_debate_contributions and parliament_find_member. The stated purpose is unambiguous and technically accurate.

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 provides explicit 'DO NOT' guidance ('DO NOT text-search by member name') and names the correct alternative workflow (parliament_find_member → parliament_get_debate_contributions). It also mentions parliament_policy_position_summary for broad topic scans and gives a concrete drill-down path via read_resource. This is exemplary usage guidance.

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