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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by detailing exactly what fields are returned and flagging optional availability ('where available', 'where one has been collected'), which helps the agent set expectations about completeness. It does not disclose not-found behavior, but for a read-only get tool this is a minor gap.

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 that is information-dense but not rambling. It front-loads the core action ('Get one insurer by slug') before listing the comprehensive set of fields. While the long list of fields makes the sentence heavy, it avoids redundancy and reads efficiently for an agent scanning for content.

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 the single parameter and existing output schema, the description covers the key aspects of what the tool returns without needing to explain the response structure. It enumerates the major groups of fields and notes optionality. It could mention the behavior when a slug doesn't exist, but with annotations covering safety and the schema providing output shape, the description is sufficiently complete for an agent to decide to use it.

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%, and the schema already describes the single slug parameter with pattern and example. The description only repeats 'by slug' without adding new semantics or constraints. Baseline of 3 is appropriate because the schema carries the load; no extra parameter insight is provided.

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 verb ('Get') and specific resource ('one insurer by slug'), and enumerates the full set of fields returned, distinguishing it from siblings like list_insurers (plural) and get_group (different entity). The single-resource focus and slug-based lookup make the intent unambiguous.

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 when a specific insurer slug is known, but it does not explicitly contrast with alternatives like search_insurers or list_insurers. No when-not-to-use guidance is given, though the 'by slug' constraint provides a clear implicit context. It would benefit from a note like 'use this when you have a slug, otherwise use search_insurers'.

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