List Trips

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

The description reveals that results are not pure trips—residences are mixed in with metadata.kind=residence—and adds real-world call constraints ($0.10 cost, API key). These details go beyond the readOnly/destructive annotations and help the agent plan the call and interpret results.

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?

Three short sentences, front-loaded with the core purpose, followed by the residence caveat and cost/auth note. Every phrase earns its place.

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?

The description is adequate for selection and covers the main caveat, cost, and auth, and an output schema exists. But with six parameters and only 17% schema coverage, the unclear from/to/limit/include_archived semantics keep it from being fully complete.

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 schema description coverage at only 17%, the description needed to clarify the five undocumented parameters. It only explains status (and only with 'planned/completed/etc.'), leaving to, from, limit, and include_archived unexplained. The cursor semantics are already in the schema, so that parameter is covered, but the remainder is not.

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 definition clearly identifies the resource (user trips) and the primary capability (status filtering), and the phrase 'prefer get_residences' distinguishes it from the closest sibling. The title 'List Trips' supplies the verb, so an agent can tell what calling it returns even before examining the 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?

It gives a concrete when-not-to-use rule: residences appear in the results but home history should be fetched via get_residences. It doesn't explicitly state when to choose this over other list tools like get_travel_history, but the use case is strongly implied by 'User trips with status filter.'

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