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

Annotations already declare the safe read/idempotent/no-destructive profile and closed-world scope, so the description adds value by disclosing the output structure (row per specification, value per plan) and the cross-product-line behavior where plans 'share few rows' – useful expectation-setting 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?

Two dense sentences, front-loaded with the core comparison behavior and the count constraint, then the return shape and the line-mixing caveat. No filler and nothing redundant.

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?

With no output schema, the description carries the return-shape burden and does so reasonably ('one row per specification and a value per plan'), while annotations cover safety and scope. Minor gaps remain about pagination or performance for 10 plans, but an agent has enough to call and interpret 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 description coverage is 100%, so lang, currency and plan_ids are fully documented in the schema, including min/max and uniqueness. The description only restates the 2-10 count and adds no format or selection detail for the two enum parameters, so it doesn't meaningfully exceed the schema baseline.

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 (compare) and resource (plans) with an explicit scope constraint ('Two to 10 plans side by side'). Combined with the output shape (one row per specification, a value per plan), an agent can distinguish this from get_plan (single) and list_plans (discovery) without opening any schema.

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 '2 to 10 plans side by side' framing makes the use case clear (multi-plan comparison) and the note about same-line vs cross-line plans gives practical guidance on which plan_ids to combine. It stops short of naming get_plan/list_plans as alternatives or stating exclusions, so it is clear context rather than full routing.

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