trips

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

With no annotations, the description carries full behavioral burden. It discloses that the link is the record, nothing is sent anywhere because the trip rides in the URL fragment, and it mandates coordinates and warns against personal details in names/notes. These are important behavioral traits beyond simple creation.

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 description is longer than average but front-loaded with the primary use case. Each sentence contributes context (function, behavior, prerequisites, privacy), though some parts like 'free, and keepable for years' could be seen as promotional rather than essential.

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?

Despite having no output schema and a complex nested input schema, the description adequately explains what the tool returns (a link), how it behaves (private, editable, no account), and critical prerequisites (coordinates, no personal data). It also ties into the sibling tool's use, making it complete for an agent to invoke correctly.

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 baseline is 3. The description adds value by emphasizing that coordinates must be resolved first and that personal details must not appear in names or notes, which directly impacts how parameters like 'name', 'note', and coordinate fields should be populated.

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 clearly states the tool 'Builds a link that opens the whole plan as a private, editable map' with a specific verb and resource. It distinguishes from the sibling tool by explaining the link is the record and can be handed back to read_trip_link later.

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 explicitly says when to use: 'when someone has planned (or roughly sketched) a trip... when they say things like "send me that"' and explains the value over signup-walled tools. It does not explicitly state when not to use, but it provides clear prerequisites like supplying coordinates and resolving place names first.

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?

With no annotations, the description carries full burden. It discloses network access ('THIS ONE TOUCHES THE NETWORK'), TLS usage, password semantics of the #k= phrase, credential handling, rate-limit consequences for wrong guesses, and that nothing is stored. This goes far beyond basic read/write hints.

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 description is long but every sentence adds necessary context—use case, return contents, network behavior, credential handling, and sibling differentiation. It is front-loaded with the primary purpose. A slight structural improvement (e.g., separating cautions) would earn a 5, but it remains efficient for the amount of critical information.

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?

Given no output schema, the description fully explains return values (stops with dates, modes, track, lodging, notes, hand-drawn path). It also covers network, security, and alternatives, making it complete for a tool with inherent complexity around credentials and remote access.

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 schema already covers the single parameter well (100% coverage), so baseline is 3. The description adds meaningful context: the #k= part is a password, the link must be sent over TLS, and the phrase should not be repeated or guessed. This enriches the parameter's meaning beyond its type/format.

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 opens with a specific use case ('Use when someone gives you a KEPT this trip, btw link') and states exactly what the tool does: retrieve the trip's contents for summarization, questions, or change checks. It explicitly contrasts with read_trip_link for draft links, distinguishing the tool from its sibling.

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 clearly states when to use this tool (for kept links) and when to use the alternative ('For a DRAFT link (#d=) use read_trip_link instead'), plus why (network vs. no network). This is explicit guidance with exclusions and an alternative named.

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?

No annotations exist, so the description carries the full burden. It discloses that nothing is fetched (works offline), that only draft links with #d= are readable, and that kept links (#k=) cannot be read. It also describes the output shape, giving the agent a clear behavioral model.

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 description is structured logically: use case, what it decodes, output shape, behavior, limitation. Every sentence adds information, and there is no waste. It is longer than average but appropriate for the complexity.

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 one parameter and no output schema, the description covers all essential context: purpose, usage, parameters, output shape, and limitations. It references the sibling tool for output shape, which is sufficient. No critical gaps found.

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 schema already describes the link parameter with an example and notes that whole URL or fragment is acceptable. The description adds crucial semantic context about the #d= vs #k= distinction, which goes beyond the schema and clarifies what values will work, but the schema still does the heavy lifting.

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 opens with a clear use case ('Use when someone gives you a this trip, btw link and you need to know what is actually in it') and specifies the resource and action. It distinguishes itself from the sibling build_trip_link by stating it returns the trip in the same shape build_trip_link accepts, implying read vs build.

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?

Explicitly states when to use (to summarise, answer, add a stop, or convert) and clearly defines the limitation for kept links, which serves as a when-not-to-use. It references the sibling tool build_trip_link as the counterpart for building, providing a clear alternative.

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