AlgoTrips

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: the data source (AlgoTrips destination guides), the shape of the payload, and the not-found behavior of returning close matches — a non-obvious trait an agent would otherwise have to discover by failing.

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 sentences with no filler; the resource and payload are front-loaded and the fallback caveat comes second, which is the right order. Slight density in the middle clause ('what the full guide covers') costs a little crispness but nothing is wasteful.

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 one-parameter lookup with an output schema, this is complete: source, contents, availability qualifier ('when available'), and failure behavior are all stated. An agent can call it correctly, and interpret a miss, without reading anything else.

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 a single parameter at 100% schema coverage, the schema already documents 'place' with examples. The description restates the same domain ('a city or region') and implies the parameter can miss via the close-matches fallback, but adds no syntax, format, or matching-rule detail beyond the schema, so the baseline 3 applies.

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 names a specific resource ('Facts about a travel destination (a city or region)') and enumerates what is returned (country, overview, guide coverage, links), which is far more specific than the bare title. It does not explicitly contrast itself with siblings like plan_trip or my_trips, though the read-only lookup framing makes the distinction inferable.

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?

Usage is only implied: an agent can infer this is the lookup to call when it needs destination background before or instead of planning. There is no explicit 'use this when…' statement and no named alternative; the only routing guidance is the not-found fallback ('it names close matches to try instead'), which is helpful but concerns retry, not tool selection.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: a hard cap of 10 results, newest-first ordering, and the sign-in requirement. It omits edge behavior such as what happens if the person is not signed in or has zero trips.

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 short sentences, front-loaded with the result set and scope, followed by the auth prerequisite. Every phrase carries information — the cap, ordering, returned fields, and sign-in requirement — with no padding.

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 zero parameters, an output schema available, and annotations covering safety, the description is nearly complete: scope, ordering, fields and auth are all stated. The remaining gap is failure/empty-state behavior and any distinction from trip_status, which an agent would still have to guess.

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?

The tool takes no parameters and the schema is empty, so there is nothing for the description to disambiguate. The baseline of 4 applies; the description correctly avoids inventing options like pagination or filtering that the schema does not support.

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 names a specific resource and scope: the signed-in account's 10 most recent trips, newest first, with the exact fields returned (title, cities, dates, status, link). It does not, however, distinguish itself from the sibling trip_status or plan_trip, so an agent must infer the boundary between listing trips and querying one trip's status.

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?

Usage is only implied by the auth prerequisite ("Needs the person to be signed in to AlgoTrips"). The description never says when to prefer this over trip_status for a single trip or plan_trip for creating one, so the routing decision with siblings is left to the agent.

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

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

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) by disclosing that the build is asynchronous (returns a build id immediately, 3-6 minutes), that AlgoTrips emails the result or failure, that unknown field names cause a refusal with a corrective message, and that booking/payment happen on algotrips.com rather than in the tool.

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?

Front-loaded with the core action, and nearly every sentence carries distinct information (async timing, email, validation, prerequisites). Some sentences are dense run-ons, e.g. the long choicesConfirmed enumeration, which slightly hurts readability without being 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 17 parameters, an output schema, and full schema coverage, the description covers the hard parts: mutation, async completion, validation failure modes, and auth requirement. The one notable gap is not telling the agent that the returned build id is meant to be used with trip_status to check progress.

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%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot express: hotelStars and interests 'shape' which hotels and activities are picked, and flights are omitted entirely when gettingAround is none. It adds real semantics on top of an already complete 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?

The opening sentence names a specific verb and resource: 'Builds a full day-by-day trip with live prices' for given cities, dates, travellers and home city. It is clearly the builder among siblings like my_trips and destination_facts, but it never names those siblings, so an agent must infer that trip_status is the follow-up to the returned build id.

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 concrete preconditions and gating rules: must be signed in, startDate is required, and with choicesConfirmed not true plus any of budget/hotel/pace/activities/gettingAround/city-order missing, nothing is built and questions are returned. It does not explicitly say when to prefer this over siblings or how to poll progress, which keeps it short of a 5.

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

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

Beyond the read-only and idempotent annotations, it discloses the signed-in requirement and phase-dependent behavior, including current work during the build and a booking link when ready. It omits operational details such as polling expectations and handling of failed or expired builds.

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 purpose and required identifier are front-loaded, and the remaining details are relevant to understanding the result. However, the long, densely packed first sentence would be easier to scan if split into lifecycle stages or bullets.

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 one-parameter read with an output schema, it provides strong lifecycle, result, and authentication context. The main remaining gap is guidance for managing the asynchronous build, particularly polling and unsuccessful terminal states.

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%, and buildId already documents both its origin and UUID format. The description's phrase 'by its build id' adds no meaningful parameter guidance beyond that 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?

Clearly defines a trip-build status lookup keyed by build ID, with distinct in-progress and ready states. This build-specific scope distinguishes it from plan_trip and my_trips without requiring their schemas.

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 build-ID prerequisite and descriptions of the building and ready phases make the calling context clear. It does not explicitly say to use it after plan_trip or when my_trips would be the better alternative.

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