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

Goes well beyond the annotations by disclosing a non-obvious side effect: unknown coverage types and statuses are auto-created in the account, which matters for a non-idempotent write. It also states the return value (new policyID) and the underlying endpoint, filling gaps the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) leave open.

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?

Single dense paragraph: operation class, purpose, prerequisites, required fields, side effect, return value, endpoint — in that order, front-loaded, with no filler sentences.

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?

For a 16-param write with no output schema, the description covers what the schema cannot: the auto-creation side effect, the returned policyID, and the required-vs-optional split. The remaining parameter detail is documented at the property level in the schema.

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?

With 16 params and 69% schema coverage, the description usefully enumerates the five required inputs and clarifies that entity_id/entity_type identify the holder and that carrier must be the full name. It adds real meaning for coverage_type/status (unknown values are created) but says nothing about the optional fields (premium, dates, custom_fields, servicing_agent_id), leaving those 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?

States a specific verb and resource ("create a policy") plus the key scoping constraint that it attaches to an existing group or individual, which cleanly separates it from agencybloc_create_group / agencybloc_create_individual. The "WRITE:" prefix immediately signals the operation class against the many read 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?

"on an existing group or individual" is a real precondition that tells the agent the holder must already exist (create/search the entity first). It does not explicitly route away from agencybloc_update_policy or mention that carrier lookup may require agencybloc_search_carriers, so no explicit alternatives are named.

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