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

Beyond the annotations (readOnly=false, destructive=false, openWorld=true), it discloses non-obvious behavior: automatic date sorting so the route draws in travel order, the 50-item batch cap, that confirmation is per-call and can be toggled off for this tool, and that a Cotlet API key with app access is required. Rich, decision-relevant context.

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?

Purpose and batch limit are front-loaded, and most sentences carry distinct information. Minor waste/phrasing opacity in 'The OK covers the whole batch', which requires inference.

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 batch-mutation tool with no output schema, the description covers batch size, ordering, confirmation expectations, cross-user visibility, and auth requirements. It does not describe the return value or partial-failure behavior when some steps are invalid, a small remaining gap.

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 the schema already documents trip_id and the step object fields including required place/date. The description restates 'each step needs a place and a date' without adding syntax or format detail, so it matches the baseline 3 for full schema coverage.

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 ('Add many steps at once') with a concrete use case (importing a past trip from CSV) and a hard limit (up to 50). It clearly distinguishes itself from the sibling polarsteps_add_step by emphasizing batch insertion into one trip.

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?

Gives a concrete usage scenario (past trip from CSV) and a behavioral precondition (confirm with the user before each call because it reaches other people). It doesn't explicitly name the single-step sibling as the alternative, so the routing guidance is implied rather than stated.

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