Tripsy

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

Annotations already cover the safety profile (readOnly=false, destructive=false, openWorld=false), and the description adds real behavior: creates are rejected without both latitude and longitude, custom slugs are only valid on Activity objects and not on lodging/transportation/expense/trip resources, and it is scoped to the authenticated user's account. It doesn't describe return behavior, but an output schema exists and covers that.

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 core guidance is front-loaded, but the text is heavily redundant: the instruction that MCP clients must convert UTC starts_at/ends_at to the activity timezone appears three times, and the 'custom slugs are only valid on Activity objects' rule is restated in three separate places. Roughly a third of the description repeats prior sentences instead of earning 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?

For a 16-parameter create tool with a nested 'data' bag and an output schema, the description covers the hard parts: mandatory coordinates, timezone conventions, category slug policy, and reservation codes. Field-level detail like price/currency pairing and the merge-precedence of the raw 'data' object is left to the schema descriptions, which is acceptable.

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 meaningful semantics: it supplies the built-in activity_type slug vocabulary (the schema declares no enum), the rule to store provider-issued codes in provider_reservation_code, and the UTC-to-timezone contract for starts_at/ends_at. That is genuine value beyond the schema, though much of the slug/custom-category text is repeated rather than refined.

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 states a specific verb and resource ('Create a Tripsy activity'), and the follow-up definition of what counts as an activity (stop, reservation, meal, tour, event, experience) helps separate it from sibling creators like tripsy_hostings_create or tripsy_expenses_create. It never names those alternatives explicitly, so sibling disambiguation is implicit rather than stated.

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 usage rules: one activity per actual stop, latitude/longitude are mandatory, 'include address when known', UTC timestamps with a local IANA timezone, and no ad hoc activity_type values such as 'sightseeing'. It stops short of stating when to use this tool instead of a hosting/transportation/expense record, which is the main gap.

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 destructiveHint=true, openWorldHint=false and readOnlyHint=false, and the description's 'Closed-world' and 'Destructive' lines largely restate those hints rather than adding new information. It adds account/trip scoping language, but says nothing about whether deletion is permanent, whether it cascades to related items, or what permissions are required — the details an agent most needs for a destructive mutation.

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 action statement is front-loaded in the first sentence and the second is a compact safety block. Slight redundancy with the annotations, but no wasted narrative and nothing buried.

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 two-parameter delete with full schema coverage, rich annotations and an output schema, the description covers purpose and scope adequately. The main residual gap is the absence of any statement about permanence or side effects of deletion.

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% for both required parameters (id and trip_id), so the schema already does the work. The description only adds 'by id' and never clarifies the role of trip_id or how it interacts with id, so baseline 3 is appropriate.

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 verb and resource ('Delete a Tripsy activity by id'), which is immediately distinguishable from siblings such as tripsy_activities_create, update, show and list. It stops short of explicitly contrasting with those siblings, but the action is unambiguous.

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: you call it to remove an activity you already have the id for. There is no guidance on prerequisites (e.g. verifying the activity with tripsy_activities_show first), no when-not-to-use case, and no mention of confirmation or irreversibility that would help an agent decide between deleting versus updating.

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, and the 'Safety: Closed-world' sentence simply restates openWorldHint=false. The one genuine addition is the requirement that clients convert UTC starts_at/ends_at into the activity timezone for display, which is real behavioral context the annotations and schema do not convey.

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 content is complete and relevant to the activity model, but it is poorly structured: a 45-item slug wall dominates the text, and creation-only guidance is interleaved with listing concerns rather than being front-loaded or separated.

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?

An output schema exists so return values need not be explained, and the mutation/write concerns are largely covered elsewhere. What is missing for a list tool is any statement of default filtering, result size or ordering, and how the broad filter set interacts with trip_id scope, leaving the definition only minimally adequate.

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, and the description does add genuine value by enumerating valid activity_type slugs and explaining that custom category slugs come from tripsy_categories_list and are valid only on Activity objects. However, it spends significant space on provider_reservation_code and latitude/longitude, which are not parameters of this tool, diluting the useful signal.

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 line 'Scheduled or unscheduled trip activities' names the resource but never states a verb like list/retrieve, so the read operation is only inferable from the tool name. Much of the body discusses activity creation (one activity per stop, latitude/longitude required), which blurs rather than sharpens what this listing tool does.

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?

'Supports common list filters' implies filtered retrieval but names no filter, ordering, or pagination behavior. There is no guidance on when to use this versus tripsy_activities_show or the related list tools (expenses_list, hostings_list), so the agent must infer the choice from names alone.

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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the 'Closed-world' safety sentence merely restates openWorldHint=false rather than adding new behavior. Nothing is said about not-found handling, permission requirements, or what is returned beyond what the output schema covers.

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 is front-loaded in a single efficient sentence, but the second sentence duplicates the openWorldHint annotation and therefore does not earn 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?

With an output schema present and full parameter documentation, the core need is covered, and closed-world scope is stated. Gaps remain around error/not-found behavior and the trip_id–id relationship, which matter for a two-identifier lookup tool.

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 both id and trip_id are already documented in the schema, which sets the baseline at 3. The description adds no format, scoping, or relationship detail (e.g., that the activity must belong to the given trip) beyond the 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?

States a specific verb and resource ('Fetch one Tripsy activity by id'), which is enough to distinguish it from the create/update/delete siblings by name and intent. It stops short of explicitly naming the sibling to use when the id is unknown, which keeps it from a 5.

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 phrase 'by id' only implies that a known activity id is a prerequisite; there is no explicit when-to-use guidance, no mention of using tripsy_activities_list to discover ids, and no stated behavior when the id is invalid or absent.

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 destructiveHint=true, idempotentHint=true, and openWorldHint=false. The description adds useful context beyond those annotations: it states the tool is closed-world within the authenticated user's account and that supplied fields are overwritten without automatic restoration of previous values. It does not explain partial-update semantics or permission requirements, but the safety profile is meaningfully reinforced.

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 safety notes are front-loaded, but the description is dominated by an inline list of roughly sixty activity_type slugs. That reference material would be better placed in an enum or structured reference, and its presence makes the description unnecessarily long and harder to scan.

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 definition covers purpose, category slug rules, and destructive overwrite behavior, and an output schema exists so return values need not be explained. However, it does not clarify whether unspecified fields remain unchanged, what permissions are required, or what happens on invalid category slugs, leaving meaningful gaps for a mutation tool.

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 baseline is 3. The description adds substantial meaning for the generic `data` object by enumerating valid built-in activity_type slugs and explaining that custom category slugs from tripsy_categories_list are valid only on Activity objects. It does not add detail for trip_id or id beyond the schema, but the activity_type guidance is valuable.

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 first sentence states a specific verb, resource, and identifier: 'Update a Tripsy activity by id.' This clearly distinguishes it from sibling verbs like create, delete, list, and show. It does not explicitly name those alternatives, but the core purpose is unambiguous.

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 description gives no when-to-use guidance relative to tripsy_activities_create or tripsy_activities_show, and no prerequisites or exclusions. The long activity_type slug list is parameter reference material, not guidance for selecting this tool over its siblings.

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 readOnlyHint=false, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description goes beyond them with genuinely useful behavior: slug auto-generation when omitted, the idempotent empty-200 response on a duplicate slug with no duplicate created, and the closed-world account/trip boundary. It stops short of describing the success response shape, though an output schema exists.

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 front-loaded sentences: purpose first, then API behavior, then scope. Efficient overall, with only mild redundancy from restating the duplicate-slug rule that the slug parameter schema already covers.

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 annotations covering safety, 100% schema coverage, and an output schema handling return values, the description supplies exactly the missing pieces: ownership scope, closed-world boundary, and idempotency semantics. An agent has everything needed to invoke it 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 description coverage is 100%, so the schema already documents all five parameters including slug generation and the duplicate-slug outcome. The description largely repeats the slug rule rather than adding new meaning, and says nothing about how the raw 'data' object interacts with typed top-level fields beyond what the schema states. 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?

States a specific verb ('Create') plus a specific resource ('custom activity category') and adds an ownership qualifier ('owned by the authenticated user'). The create-vs-list/show/update/delete distinction from siblings is unambiguous from the name and opening sentence.

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 description implies usage (creating a user-owned category) and explains the duplicate-slug outcome, which is a de facto precondition check. However, it never explicitly says when to prefer this over alternatives such as checking tripsy_categories_list first or using tripsy_categories_update for existing categories, and gives no exclusion guidance.

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?

The word "Soft-delete" is genuinely valuable because it tells the agent the effect is recoverable rather than permanent, and "owned by the authenticated user" discloses the authorization boundary. However, the two "Safety" clauses largely restate the supplied annotations (openWorldHint=false, destructiveHint=true) rather than adding new detail such as cascade effects on activities referencing the category or how to undo the soft delete.

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 with the action, scope, and selector front-loaded, and no filler or marketing language. The trailing "Safety" block is mildly redundant with the annotations, but it is compact enough not to obscure the primary sentence.

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 delete tool with an output schema and full annotation coverage, the essentials are present, so the agent knows what it deletes and whose data it touches. What remains missing is the consequence detail that matters for a destructive operation: what happens to trips or activities referencing the category, and whether/when the soft delete can be reversed.

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 there is a single required parameter documented as 'Tripsy resource id'. The description's "by id" and "owned by the authenticated user" only confirm what the schema implies, adding no format, naming, or lookup guidance (e.g. how to obtain the id). 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 verb and mode ("Soft-delete"), a specific resource ("custom activity category"), an ownership scope ("owned by the authenticated user"), and the key selector ("by id"). That is enough to distinguish it from the sibling categories_create, categories_update, categories_show, and categories_list without opening 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?

Usage is only implied by the verb: an agent can infer 'call this when a category should go away', but nothing states when to prefer this over categories_update (e.g. renaming/archiving) or whether a soft-deleted category can be restored. No prerequisites or exclusions are given, so the agent must infer selection logic.

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?

The visibility rule (owned by caller or by users sharing an active trip) is real behavioral information beyond the annotations. However, the 'Safety: Closed-world' sentence only restates openWorldHint=false and adds nothing, and pagination/result-size behavior is left unaddressed despite the output schema covering the return shape.

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 substantive sentences are front-loaded with scope before the practical hint about activity_type. The trailing 'Safety: Closed-world' clause is boilerplate that duplicates an annotation and could be dropped.

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 an output schema present, return values need not be explained, and all four optional parameters are fully documented in the schema. What remains is the scope statement and the cross-reference to activity endpoints, which are covered; only pagination/ordering behavior is unstated.

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 fields, fields_exclude, deleted, and updated_since are already documented in the schema, including their query-parameter mapping. The description adds no parameter-level meaning, so the baseline of 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?

States a specific verb and resource (list custom activity categories) plus a precise visibility scope: categories owned by the caller or by users sharing an active trip. That scope is what separates it from categories_show/update/delete, though it never names those siblings explicitly.

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 downstream use case — the returned slugs are valid activity_type values on activity endpoints — which tells an agent why and when to call it. It stops short of exclusions, e.g. it doesn't say to prefer categories_show when a specific slug's details are needed.

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 readOnlyHint, idempotentHint, closedWorldHint=false/openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered by structured data. The "Safety: Closed-world ... authenticated user's Tripsy account and accessible trips" sentence largely restates the openWorldHint annotation, though "accessible trips" adds a small amount of authorization-scope context, and "visible" hints at visibility filtering. Return shape is covered by the output schema, so its absence from the description costs nothing.

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 with the operation front-loaded and the scope constraint second. The "Safety:" prefix is slightly boilerplate in front of a constraint that annotations already encode, but nothing is wasted at length.

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-only, idempotent fetch with a full output schema and complete annotations, the description covers what the tool does and its account boundary. Only the relationship to the list endpoint is unstated.

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 100% schema description coverage and a single required parameter already documented as "Tripsy resource id", the schema carries the semantics. The description only adds the notion of visibility ("one visible") and the entity type the id refers to, which is marginal added value.

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 states a specific verb+resource pair ("Fetch ... custom activity category") and constrains it to a single record by id, which separates it from the sibling list/create/update/delete category tools. It does not explicitly name the list sibling as the multi-record alternative, so it stops just short of full differentiation.

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?

"by id" implies the caller must already hold an identifier, and "one" implies enumeration belongs to another tool, but neither the list alternative nor the case where no id is known is stated. Usage is inferable rather than guided.

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 destructiveHint=true, idempotentHint=true and openWorldHint=false, so most of the 'Safety' sentence restates structured data. The one genuinely additive point is that previous values are not automatically preserved or restored, which tells the agent there is no undo path, plus the account-scoping note. Useful but largely duplicative.

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 the purpose front-loaded and the safety caveat second, which is the right ordering for a mutation tool. The 'Safety:' label is slightly boilerplate and could be folded into a single clause.

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?

An output schema exists and the input schema is fully described, so the description needn't explain return values. Given the tool's complexity (nested object parameter, destructive overwrite semantics), the description covers scope and irreversibility adequately, though it omits update semantics for omitted fields.

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 every parameter including the nested `data` object is already documented with examples (color as hex without '#', name such as 'Golf Clubs'). The description adds nothing about parameter behavior, merge order, or which fields are mutable, 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 first sentence gives a specific verb ('Update'), a specific resource ('custom activity category'), and a scope ('owned by the authenticated user by id'), which separates it from the create/delete/list/show siblings in the categories family. It stops short of naming an alternative tool or clarifying when a partial update is preferable to a full overwrite, so it lands just below the top mark.

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?

There is no explicit when-to-use or when-not-to-use guidance and no mention of the siblings (e.g. categories_show to read current values before overwriting, or categories_delete for removal). The only implied usage is 'by id', leaving the agent to infer prerequisites and alternatives entirely.

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 destructiveHint=true and openWorldHint=false, so the safety sentences are partly redundant. However the description adds genuinely new behavior: cascading deletion of activity, lodging and transportation assignments, plus the uncertain side effect of revoking pending invitations, which the agent cannot infer from annotations or schema.

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 blocks in a sensible order: action and consequences, parameter sourcing, then safety traits. No filler, and the irreversible effects are front-loaded where an agent scanning the definition will see them.

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 an output schema present, return values need no explanation, and both parameters are fully documented. What remains thin is permission/ownership requirements and whether removal is reversible, which would matter for a destructive collaborator operation.

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% and both parameters are already documented, including the warning that user_id is not a favorite or invitation id. The description only restates the source tool for user_id and adds nothing about trip_id, so 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?

States a specific verb and resource ("Remove a guest from a trip") and immediately lists the effects: access revoked, assignments cleared. This is clearly distinct from siblings like tripsy_collaborators_invite and tripsy_collaborators_update, so an agent can route correctly without opening 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?

"Use the user id from collaborators" tells the agent where to source the required identifier, effectively pointing at tripsy_collaborators_list as a prerequisite. It does not state when removal is inappropriate or what to do if the guest owns data, so there is no explicit exclusion guidance.

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 openWorld and destructive, but the description adds the non-obvious failure mode: "The API can return success without adding a guest," which the annotations cannot convey. It also concretizes the destruction as unsendable email plus trip-data exposure to external recipients. The closing sentence partially restates the hints rather than adding new facts, keeping it short of a 5.

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 purpose and usage, then safety, which is the right ordering for a destructive tool. The safety block is slightly padded: "This applies even when invitations are optional or a favorite guest is added directly" re-states the destructive hint in a way that costs words without new 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?

Covers purpose, preconditions, ordering (check collaborators after), silent-success risk, and external side effects; an output schema exists so return values need no explanation. Nothing material is missing for calling this correctly and safely.

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 real meaning for invited_user_email: confirmed favorites can be added directly, which tells the agent that a known favorite address takes a different path than an arbitrary invite. It does not clarify how the permissions sub-fields interact with the inviter's own limits beyond what the schema already says.

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 ("Invite a guest to an existing trip by email") and immediately scopes it against a near-neighbor workflow ("guest_invites is only processed during trip creation"). An agent can distinguish this from tripsy_collaborators_list/update/delete without opening a 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?

Explicitly says when to use it (existing trips) and when not (creation flow), and gives the operative precondition ("Requires permission to add guests"). It also names the follow-up action after calling ("check collaborators afterward"), so the agent knows the tool is not self-verifying.

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?

The 'Closed-world' sentence essentially restates the supplied openWorldHint=false annotation rather than adding new behavioral information. It says nothing about ordering, pagination, whether the trip owner is included in results, permission requirements, or what happens when the trip is inaccessible — all of which the annotations do not cover.

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 core purpose is front-loaded in one tight sentence with zero filler. The second sentence is largely redundant with the annotations, which is a minor efficiency loss but not a structural problem.

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?

This is a simple one-parameter read tool; safety hints are covered by annotations and return values by the existing output schema, so the description needn't carry those burdens. The remaining gap is small — no guidance on obtaining the trip_id or on behavior when access is denied.

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?

There is a single required parameter with 100% schema description coverage ('Tripsy trip id.'). The description adds no meaning beyond that — it does not say where a trip_id comes from (e.g., tripsy_trips_list) or what format it takes, 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 verb and resource ('List collaborators') and adds scope detail the name alone doesn't convey: pending invitations are included. Against siblings like tripsy_collaborators_invite/update/delete, an agent can immediately tell this is the read-only enumeration path.

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 implied by the verb and by the necessary trip_id, so an agent will infer it should be called to inspect who has access to a trip. However, there is no explicit when-to-use or when-not-to-use statement, and no mention of related alternatives (e.g., invite to add a collaborator).

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 destructiveHint=true and openWorldHint=false, but the description adds real substance: it names exactly which permissions can be revoked or overwritten (editing, document/expense visibility, travel/notification preferences) and notes server-side permission enforcement. The 'Closed-world' sentence largely restates openWorldHint=false, so some credit is lost for repetition.

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 key routing rule is front-loaded, which is good, but the destructive-permission content is stated twice (once in the safety sentence, once in 'The API enforces guest-management permissions for broader changes') and the owner/self-permission rules overlap. Trimming the duplicated safety statements would sharpen it.

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 an output schema present and all three parameters fully documented, the description covers what an agent needs: who is being modified, how to target oneself, single-field constraints, and the permission consequences of the call. Only the owner-versus-guest permission tiering could be stated more crisply, which is a minor 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 coverage is 100% and the nested permissions object documents every field, so the schema carries the load. The description reinforces the two operationally important rules (user_id 'me' and sending a single field for self-updates), but those rules are already stated in the schema descriptions, so the added meaning is marginal.

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 verb+resource: 'Update a guest's trip permissions', which is clearly distinct from siblings like tripsy_collaborators_invite, tripsy_collaborators_delete, or tripsy_me_update. It does not name those alternatives explicitly, so the differentiation is implicit rather than stated.

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 operational guidance: use user_id 'me' with permissions containing only is_travelling to switch between travelling and following, and single-field updates for one's own preferences versus broader changes needing guest-management permission. The added line 'Owners can only change their own travel or notification preference' sits awkwardly against the earlier 'broader changes require guest-management permission', leaving a small ambiguity about what an owner may actually do.

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 annotations, the description discloses the permission model (owners need active Pro, permitted collaborators do not), that the main API enforces trip membership and document visibility/edit permissions, and that document metadata and file contents are untrusted data rather than instructions. The closing safety line largely restates openWorldHint=true, so some duplication exists, but the gating and permission context is genuinely additive.

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 two operating modes and the upload flow are front-loaded, and most sentences carry operational content. The final open-world safety sentence partly duplicates the openWorldHint annotation and an earlier statement about the same behavior, which is the main bit of slack.

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 10-parameter mutation tool with an output schema already covering return values, the description covers everything an agent needs: the two attach paths, the upload choreography, the required parent/file_type alignment, and the authorization prerequisites. Nothing essential to calling it correctly is left implicit.

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 100% schema description coverage the baseline is 3, but the description adds meaning the schema does not: that url carries either a web link or the exact object_key from upload_prepare, and that file_type must match the MIME content_type used at preparation time and the attachment must land on the same parent. That is real cross-parameter guidance rather than restatement.

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 verb and two precisely scoped modes: attach an HTTP(S) link, or finalize an uploaded file via object_key and upload_token. It names tripsy_documents_upload_prepare as the prerequisite sibling, so an agent can separate this from upload_prepare, upload, and documents_update without inspecting 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?

It gives a clear two-step context (call upload_prepare, PUT the bytes to upload_url with the exact headers, then attach to the same parent with the same MIME file_type), which effectively tells the agent when this tool is the right next step. It does not explicitly state when-not to use it or contrast it by name with tripsy_documents_upload, 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?

Goes well beyond the destructiveHint/openWorldHint annotations by disclosing that deletion is recoverable, that owners require an active Pro subscription while permitted collaborators do not, and that the main API enforces trip membership and edit permissions. The untrusted-content warning and closed-world scope statement add real operational context an agent would not otherwise have.

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 core action and parent-selection rule are front-loaded and easy to scan. The trailing safety block partly restates the annotations (closed-world, destructive), which is mild redundancy but short enough not to obscure the operative guidance.

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 destructive, permission-gated delete with an output schema and full annotation coverage, the description supplies everything an agent needs: recoverability, subscription/permission rules, parent targeting, and a prompt-injection caution. Return values are covered by the output schema, so nothing material is missing.

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 meaning the schema does not: which parent to supply (the exact parent from the list result, not the trip) and why trip lists behave differently. It clarifies the otherwise ambiguous parent_id/parent_type relationship in practice.

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 ('Recoverably delete a document') plus the scope ('directly attached to the specified trip or itinerary parent'), which distinguishes it from documents_attach, documents_update, and the various *_delete siblings by parent type. An agent can identify the operation without opening 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?

Explicitly tells the caller to supply the exact parent_type and parent_id from the list result for child-object documents, and the schema-independent context (trip lists aggregate attachments) reinforces when the parent parameters are needed. It does not name a specific alternative tool to use first (e.g. tripsy_documents_list), so it stops short of full routing guidance.

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, yet the description adds substantive behavior: the URL is temporary with an expiry, permission enforcement is server-side (trip membership plus document visibility/edit rights), and entitlements differ by role. The closing 'Safety: Closed-world' sentence largely restates openWorldHint=false and does not earn its space.

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 core behavior is front-loaded in sentence one, which is good, but the definition runs five sentences and the final safety/closed-world line duplicates the openWorldHint annotation. The untrusted-data warning is valuable; the account-scope restatement is filler.

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?

An output schema exists, so return values need not be enumerated, and the description still flags the expiry field and the URL-document variant. Permission model and entitlement preconditions—the main failure modes for a single-id read—are covered, leaving little an agent would need 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?

Schema description coverage is 100% for the single `id` parameter, so the schema already carries the burden. The description only implicitly narrows `id` to a document identifier via 'accessible document', adding no format, prefix, or lookup guidance beyond that.

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 first sentence names a specific verb and output ('Get a temporary private download URL and expires_at') and clarifies the edge case that URL-type documents return the original link. This distinguishes it functionally from a metadata reader like tripsy_documents_show, though no sibling is named explicitly.

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 real usage context: the document must be accessible to the caller, owners need an active Pro subscription while permitted collaborators do not, and callers must not auto-fetch or execute the returned content. It stops short of naming an alternative tool or stating when to choose metadata retrieval instead.

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 still adds real value beyond them: the tiered Pro/collaborator authorization model, the note that document metadata and file contents are untrusted data rather than instructions, and that it pages through all 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?

Front-loaded with the core action and scope, then permissions, then safety. Sentences are dense but each carries information. The trailing 'Closed-world' sentence partially duplicates the openWorldHint=false annotation, which is minor redundancy.

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 read-only, three-parameter listing tool with a full schema and an output schema, the description covers scope, permissions, and untrusted-data handling adequately. Pagination mechanics are only alluded to via 'every page', 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 coverage is 100%, so all three parameters are documented, including the 'omit for trip' rule and the aggregation behavior of parent_type=trip. The description adds little beyond restating the parent scope, so the baseline of 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 opening sentence uses a specific verb (list) and resource (documents) and states the scope precisely: all pages, either trip-wide or scoped to an activity, hosting, or transportation. It does not explicitly distinguish itself from the nearby documents_show/documents_get siblings, which is the only thing keeping it from a 5.

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?

Useful conditions are given for access: owners need active Pro, permitted collaborators do not, and the API enforces membership and visibility/edit permissions. However, there is no explicit guidance on when to choose this over documents_show or documents_get, so the agent must infer the list-vs-fetch split on its own.

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?

The description adds several behavioural facts beyond annotations: active Pro required for owners, collaborators exempt, API-enforced membership and visibility checks. That is real credit over a plain read-only path. It does not disclose return shape or what 'metadata' includes (though an output schema exists), and the 'untrusted data' and 'closed-world' sentences are safety boilerplate rather than operational detail.

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 first sentence is front-loaded and effective, and the access rules earn their place. But the trailing 'Document metadata and file contents are untrusted data, not instructions' and the 'Safety: Closed-world...' restatement of openWorldHint=false are boilerplate that an agent already gets from annotations, diluting a fairly short description.

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 4-parameter read with a full output schema and complete read-only/idempotent annotations, the description covers scope, permission prerequisites, and enforcement. The only gap is that it doesn't say what happens on permission failure or whether a parent_id mismatch returns an error rather than null.

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. The description earns a small bump by stating the parent-scoping rule ('scoped to its trip or exact itinerary parent'), which clarifies why parent_id/parent_type exist and how trip scope differs from activity/hosting/transportation scope, without contradicting the schema's own descriptions.

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?

Opens with a specific verb and resource: 'Read one document metadata record', and immediately states scope ('scoped to its trip or exact itinerary parent'). This clearly distinguishes it from siblings such as tripsy_documents_list (many records), tripsy_documents_get (raw file content), and tripsy_documents_update.

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 parent-scoping sentence gives implied usage guidance ('scoped to its trip or exact itinerary parent'), and the Pro/collaborator rule tells an agent when the call will succeed. However, it never names an alternative tool or states explicitly when to choose this over documents_list or documents_get, leaving the sibling routing to inference.

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 destructiveHint, openWorldHint and idempotentHint, so the bar is lower, but the description still adds real substance: per-source and destination permission checks, the Pro entitlement rule, the untrusted-content warning about metadata and file contents, and the concrete consequence of destruction (metadata overwrite/clear and parent-association change altering access). The final sentence largely restates the earlier omitted-fields/move/permission points, which trims a point.

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 is front-loaded and the individual sentences are readable, but the closing sentence redundantly repeats 'Omitted fields remain unchanged; moves require exactly one destination and API permission checks', and the permission story is spread across three separate sentences that partially overlap.

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 complex mutation tool with a move operation, the description covers permissions, entitlement rules, destructive effects, external URL risk and untrusted data, and an output schema exists so return values need no explanation. The only gap is that it never distinguishes this tool from attach/upload, which an agent might confuse when repositioning existing documents.

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% and the description adds little beyond it: the 'exactly one destination' rule and 'empty clears it' semantics are already spelled out in the per-parameter schema descriptions. Baseline 3 applies since the schema carries the parameter meaning.

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 gives a specific verb (edit/move) plus resource (document) and enumerates the mutable fields and the mutually exclusive destination move, which cleanly separates it from siblings like tripsy_documents_upload, tripsy_documents_attach and tripsy_documents_delete.

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 states the preconditions for calling (permission checks on source and destination, owner needs active Pro, collaborators do not, trip membership and edit visibility enforced) and that omitted fields are left alone. It does not explicitly name a sibling to use instead when the goal is creating, attaching or deleting a document, so it stops short of full when-not guidance.

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 annotations, the description discloses the actual mechanics (bytes go to an API-issued private S3 URL, then the document is attached in Tripsy), that no Tripsy credentials reach S3, the Pro entitlement requirement for owners, and that server-side membership/permission checks apply. It also flags file contents and metadata as untrusted data, which is real behavioral guidance. Slight deduction because the closing 'Safety: Open-world...' sentence largely restates the openWorldHint annotation and the S3 URL behavior already described above.

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 most important constraints — size limit and the sibling alternative — are front-loaded in the first two sentences, which is good structure. However, the safety sentence repeats the S3 upload flow and open-world fact already stated earlier, and could be trimmed without losing 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?

For a mutation tool with an output schema present, the description covers the essentials: size limits, the correct sibling workflow, permitted input forms, entitlement rules, server-side permission enforcement, and credential handling. Nothing critical for a correct call is missing, though the entitlement/permission sentences sit slightly at odds with the schema's parent_id/parent_type complexity, which is left to the schema alone.

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 all eight parameters, including the 8 MiB decoded limit and the no-paths rule for content_base64. The description's parameter-related content (size cap, no paths/URLs) duplicates the schema rather than adding new semantics. Baseline 3 is the right score when the schema 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 first sentence names a specific verb and resource ('Upload and attach standard base64 document bytes') plus a hard size bound, and the second sentence names the sibling alternatives (upload_prepare then attach) for the out-of-scope case. An agent can distinguish this from tripsy_documents_attach and tripsy_documents_upload_prepare 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?

It gives an explicit routing rule: files up to 8 MiB use this tool, larger files must use upload_prepare followed by attach. It also states clear exclusions ('No file paths or arbitrary upload URLs are accepted'), so the agent knows what not to attempt.

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 only declare this is a non-read-only, closed-world, non-destructive operation; the description adds substantive context beyond that: no local server file reads, the receipt expiring alongside the URL, the enforced trip membership and document visibility/edit permissions, and the 25 MiB ceiling. The one weak spot is that 'The receipt expires with the upload URL' never states an actual lifetime, so an agent cannot plan around the expiry. It does not contradict the annotations, which correctly describe a write-adjacent but non-destructive preparation step.

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 action, the size cap, and the required follow-up call are front-loaded in the first two sentences, which is the right ordering. The tail is weaker: the untrusted-data sentence is generic prompt-injection boilerplate and the 'Safety: Closed-world' clause largely restates openWorldHint=false from the annotations. Neither is fatal, but both cost words without adding tool-specific signal.

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 multi-step mutation tool this covers the essentials: the ceiling, expiry, permission model, the follow-up call, and the clarification that nothing on the server is read. An output schema exists, so the description is correctly silent on return values. What is missing is any concrete expiry duration and any differentiation from the adjacent tripsy_documents_upload tool.

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 every parameter including parent_id/parent_type conditional semantics is already documented in structured form. The description reinforces the content_length ceiling and notes that trip_id access is API-enforced, but adds no new meaning for the parent_id/parent_type pairing or filename handling. Baseline 3 is the correct landing point when the schema carries the semantics.

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 first sentence names a specific verb and resource pair ('Create a private presigned S3 PUT URL and upload_token') plus a hard size limit, which is far more than a restatement of the name. It also disambiguates from the attach step by naming tripsy_documents_attach as the follow-up. It stops short of a 5 because the sibling tripsy_documents_upload sits right next to it in the namespace and is never mentioned, so an agent still has to guess which of the two upload paths to pick.

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 description gives an explicit call order: prepare here, PUT the bytes with the returned headers, then call tripsy_documents_attach. It also states the prerequisite that owners need active Pro while permitted collaborators do not. It lacks any when-not guidance and does not contrast with tripsy_documents_upload, so the agent has no rule for choosing between the two upload tools.

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 readOnly/idempotent/non-destructive annotations, the description adds real behavioral facts: entitlement rules (Pro for owners, permission-based access for collaborators) and that full original email content plus attachments are returned by the API. The security note about treating email content as untrusted data is genuinely useful for an agent handling returned content. The 'Safety: Closed-world' sentence largely restates openWorldHint=false, which is redundant but not harmful.

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 scope statement is front-loaded and the sentences are dense but purposeful: listing behavior, permissions, and untrusted-content handling. The closing 'Safety: Closed-world' line duplicates the openWorldHint annotation and could be dropped without losing 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?

An output schema exists, so return values need no explanation, and the description covers the remaining gaps: pagination ('every page'), parent scoping rules, aggregation semantics, and access prerequisites. Nothing an agent needs in order to invoke this correctly is missing.

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 all three parameters already explain themselves, including the parent_id/parent_type dependency. The description reinforces that trip-level lists aggregate attachments across the trip but adds no syntax, format, or edge-case detail beyond what the schema states. Baseline 3 is appropriate when the schema carries the parameter burden.

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 verb and resource ('List every page of booking emails') and scopes it to attachments anywhere in a trip or on one activity/hosting/transportation, which separates it from a single-email fetch like tripsy_emails_show. It does not name that sibling explicitly, so the differentiation is implied by the list-vs-show naming rather than stated.

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 concrete conditional guidance: parent_id is required for activity/hosting/transportation and omitted for trip, and trip-level listing aggregates the whole trip. It also spells out who may call it (owners need active Pro; collaborators need document visibility permission and can call without Pro), which is exactly the pre-call context an agent needs. It stops short of pointing at related tools for other email workflows.

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 readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so safety is largely covered. The description still adds genuinely non-derivable behavior: the permission gate, the Pro exemption for collaborators, and the prompt-injection caveat that bodies and attachments are untrusted data rather than instructions. It does not describe error behavior when access checks fail, which keeps it below a 5.

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 is front-loaded in the first clause and follows with permission, safety, and alternative-use notes in a logical order, with no filler sentences. It is somewhat dense with comma-separated qualifiers, but every clause carries 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?

For a read-only fetch with full schema coverage, complete annotations, and an output schema that carries return values, the description covers what remains: permissions, scoping, untrusted content, and the mutation sibling for rename/move. Only failure and empty-result behavior are unaddressed.

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 100% schema coverage the parameters are already fully documented, so the baseline is 3. The phrase 'scoped to an accessible trip or exact itinerary parent' loosely reinforces the trip_id/parent_id relationship and the 'exact' qualifier hints that parent matching is strict, but it adds no syntax or format detail beyond the 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 ('Retrieve') and resource ('one original booking email and its attachments') and scopes it to 'an accessible trip or exact itinerary parent'. The singular 'one' plus 'original' differentiates it from the sibling list tool tripsy_emails_list, so an agent can select it without opening a 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 supplies prerequisites ('Requires document visibility permission; permitted collaborators do not need their own Pro') and routes a related operation elsewhere ('Use tripsy_inbox_update to rename or move'). What is missing is an explicit when-not-this-tool note covering tripsy_emails_list versus this single-fetch, and when parent_type scoping should be preferred over a plain trip lookup.

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?

The annotations already declare readOnlyHint=false, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description's 'closed-world within the authenticated user's Tripsy account and accessible trips' adds a useful scoping/auth note that reinforces the openWorldHint=false annotation rather than merely repeating it. It still says nothing about what happens on duplicate submission, field validation failures, or permissions required to write into a shared trip.

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 purpose before field hints and safety scoping. The 'Safety:' prefix is slightly awkwardly formatted but no sentence is filler for a tool this small.

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?

An output schema exists, so return values need no explanation, and the annotations carry the mutation/open-world profile. For a two-parameter create tool with a free-form data object, naming the expected fields plus the account scoping covers most of what an agent needs. The remaining gap is field requiredness inside 'data' and any resulting-expense identifier the agent might need afterward.

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%, but the critical 'data' parameter is an untyped object with additionalProperties=true, so the schema enumerates nothing. The description compensates by naming the expected fields (title, price, currency, date), which is genuine meaning beyond the structured data. It does not specify which of those fields are required versus optional, keeping it short of a 5.

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 first sentence gives a specific verb and resource: 'Create a Tripsy expense,' which distinguishes it from the expenses update/list/show/delete siblings. It does not explicitly contrast with the other create tools (activities, categories, hostings), but the resource noun makes the intent unambiguous.

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?

There is no when-to-use guidance, no mention of prerequisites such as needing an existing trip_id, and no routing to alternatives like tripspy_expenses_update when the expense already exists. Usage is only implied by the verb 'Create.'

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?

The safety sentences largely restate what the annotations already declare (destructiveHint=true, openWorldHint=false). They add scoping language about the authenticated account and accessible trips, but disclose nothing new about the deletion itself — whether it is permanent or soft, whether it cascades to splits/attachments, or what error occurs for a missing id.

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 with the action front-loaded and no filler. The second sentence is largely boilerplate duplicating the annotations, which keeps it from a 5.

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 output schema and annotations cover return shape and the destructive/closed-world profile, so the basics are present. For a destructive delete tool, however, the description omits the key behavioral detail an agent needs — irreversibility and side effects — leaving a meaningful 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?

With 100% schema description coverage, both required parameters (id, trip_id) are already documented in the schema. The description adds no meaning beyond that, such as why trip_id and id are both required or what id namespace is used, so the baseline of 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 states a specific verb and resource — 'Delete a Tripsy expense by id' — which cleanly separates it from the expenses_create/list/show/update siblings. It stops short of naming alternatives explicitly, but the operation is unambiguous.

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?

There is no guidance on when deletion is appropriate versus when to use tripsy_expenses_update, no mention of preconditions (permissions on the trip, whether the expense exists), and no advice on confirming irreversibility before calling. Usage is only implied by the verb.

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?

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, and the "Closed-world" sentence simply restates that last flag rather than adding new information. Nothing is said about pagination, result ordering, behavior when the trip_id is unknown or inaccessible, or how the `deleted` and `fields` options alter the response.

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, nothing padded or redundant in structure, and the resource is front-loaded. The middle clause "Supports common list filters" is vague filler that conveys less than its word count suggests, keeping it from a 5.

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 7 parameters, a required trip_id, and multiple sibling list/show tools, an agent needs to know scope (single trip only?), whether deleted records appear by default, and how this relates to tripsy_expenses_show. Annotations and the output schema cover safety and return shape, but the description leaves the invocation context largely unexplained.

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 explains every one of the 7 parameters, including deleted, updated_since, and fields/fields_exclude. The description's "common list filters" adds no concrete meaning (it does not enumerate which filters exist or note that trip_id is required), leaving it at the high-coverage 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?

The fragment "Trip expenses." names the resource and "Supports common list filters" implies a list operation, but no explicit verb+resource statement is given; an agent infers 'list' from the title and tool name rather than the description. It does not distinguish this from siblings like tripsy_expenses_show (singular fetch) or tripsy_activities_list beyond the resource noun.

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?

No guidance on when to use this versus tripsy_expenses_show, tripsy_trips_list, or other list endpoints, and no prerequisites (e.g., needing a valid trip_id, or access to the trip). The only cue is "common list filters," which does not say which situations call for them.

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?

The safety sentence largely restates what the annotations already declare (openWorldHint=false, readOnlyHint=true), with the mild addition that scope is limited to accessible trips. It says nothing about not-found behavior, whether an id must belong to the given trip_id, or error conditions, so beyond annotations it adds little.

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 with the action front-loaded and no filler. The second sentence is partly redundant with the annotations, which costs it a point, but nothing is bloated.

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?

This is a simple two-parameter read with an output schema and full annotation coverage, so the description does not need to explain return values. Only the relationship between trip_id and id, and not-found handling, are unaddressed – minor gaps for a tool of this complexity.

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 both parameters are documented only generically ("Tripsy subresource id", "Tripsy trip id"). The description's "by id" adds no meaning about how id relates to trip_id or what format either takes, so it contributes nothing beyond the 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?

"Fetch one Tripsy expense by id" states a specific verb and resource and, via "one ... by id", implicitly separates it from tripsy_expenses_list and the create/update/delete siblings. It stops short of naming a sibling or the collection-vs-single contrast explicitly, so it is clear but not maximally differentiated.

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: fetch when you already have an expense id. There is no explicit guidance on when to prefer this over tripsy_expenses_list (e.g., to resolve a single known id) nor any stated prerequisite that trip_id must be a trip the user can access.

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 destructiveHint=true, idempotentHint=true and openWorldHint=false, so the description's safety lines largely restate them, though it does add real nuance: previous values are not preserved or restored, and scope is limited to the authenticated account and accessible trips. The critical gap is that it never says whether 'data' is a partial merge (unmentioned fields untouched) or a replacement (unmentioned fields cleared), which matters most for a destructive update.

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, verb and target front-loaded, with the safety caveats compactly labeled. Slight redundancy with the annotation block keeps it from being maximally efficient, but nothing is padded.

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?

An output schema exists, so return values need not be explained. However, for a destructive update over a free-form 'data' object, the description should clarify partial-vs-full replacement and error behavior on an invalid id; those omissions leave a meaningful hole for an agent deciding how to call 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 coverage is 100%, so id and trip_id are already documented, giving a baseline of 3. The description adds nothing about the 'data' payload — it does not list which expense fields are updatable or how they are encoded, even though 'data' is an open-ended object with additionalProperties=true where the schema is least helpful.

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 verb and resource ("Update a Tripsy expense") plus the lookup key ("by id"), so it is distinguishable from tripsy_expenses_create/delete/list/show. It stops short of explicitly contrasting itself with siblings such as show or delete, but the operation is unambiguous.

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 it should be used when modifying an existing expense that already has an id. There is no guidance on prerequisites (e.g., calling tripsy_expenses_show first to obtain current values), no statement about when to prefer delete+create, and no exclusions.

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 readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the bar is lower. The description still adds real value by warning that pending invitations are mixed in and that the two id fields mean different things, though it says nothing about pagination or result volume.

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 tight sentences, front-loaded with the purpose and followed by the id disambiguation. The 'Safety: Closed-world' clause largely restates openWorldHint=false, which is the one redundant element.

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?

An output schema exists, so return values need no explanation, and the description covers the one genuinely ambiguous part of the response: which id is the favorite record and which is the user. Missing only guidance on ordering, volume, or empty-state behavior.

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 zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. Schema coverage is listed at 100% but the schema is an empty object with additionalProperties false.

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 verb and resource: 'List all account favorite guests and pending outgoing favorite invitations.' It also makes clear the result mixes two record kinds (favorites and pending invitations), which an agent could not infer from the name alone.

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 downstream guidance ('use favorite_user.id when a user id is needed'), which tells the agent how to consume the result, but never states when to call this versus alternatives or what prerequisites exist. The context is implied by the name rather than spelled out.

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 readOnlyHint=false, openWorldHint=false and destructiveHint=false; the description restates the closed-world scope in more concrete terms (authenticated user's Tripsy account and accessible trips) and adds the UTC-storage/local-timezone-display contract, which is genuine behavioral context. However it says nothing about duplicate handling, whether a failed required trip_id errors, or the precedence of the raw `data` object during merge.

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 opening and the activity-vs-lodging rule are well front-loaded, but the UTC/timezone display instruction is repeated in the description and again in three separate schema properties, and the 'Include name, address, ...' sentence is a verbatim echo of the schema. Roughly a third of the text could be cut without loss.

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 16 parameters, a nested `data` object and an output schema, the description covers the essentials: what is created, the recommended field set, the timezone/UTC contract, and the account scope. The only substantive gaps are the `data` merge precedence (deferred entirely to the schema) and create-vs-update guidance, both minor given rich structured fields.

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 schema already documents all 16 parameters thoroughly, including UTC format and IANA timezone rules. The description's field list and UTC/timezone guidance largely duplicates those schema descriptions rather than adding new meaning, so the baseline of 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 opens with a specific verb and resource ('Create a Tripsy hosting') and immediately distinguishes the resource from its nearest sibling domain ('Use hostings for hotels and lodging rather than activities'). An agent can distinguish this from tripsy_activities_create and tripsy_transportations_create without consulting 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?

It gives a clear creation context and an explicit domain-selection rule versus activities, plus a recommended field set for well-formed hostings. It does not state when to use tripsy_hostings_update instead of create for an already-existing lodging, so the create-vs-update boundary is left implicit.

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?

The annotations already declare destructiveHint=true and openWorldHint=false, and the description's 'Closed-world' and 'Destructive' lines largely restate them rather than adding value. The only marginal addition is the auth scope ('authenticated user's Tripsy account and accessible trips'). It says nothing about irreversibility, cascade effects on linked subresources, or failure behavior when the id is invalid.

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 with the operation front-loaded, and no filler. The safety sentence could be tightened since it duplicates annotation data, but nothing is wasted in length.

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?

An output schema exists, so return values need not be explained, and the two required parameters are fully documented. However, for a destructive mutation the description omits the consequences of deletion (irreversible? cascade?) and the auth/permission requirement, leaving meaningful gaps.

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 defines both required parameters (id and trip_id). The description notes targeting 'by id' but does not clarify the relationship between the hosting id and the parent trip_id or their expected formats, so it adds no meaning beyond the 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?

States a specific verb and resource ('Delete a Tripsy hosting') plus the identifier used to target it ('by id'), which distinguishes it from hostings_create/list/show/update. It does not explicitly name the sibling it replaces, but the delete verb makes the distinction unambiguous.

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?

There is no guidance on when to delete versus update/archive, no prerequisite checks (e.g., confirming the hosting exists or is not referenced by activities/expenses), and no mention of the required trip_id being a scope parent. The agent must infer all usage context.

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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the closing "Safety: Closed-world..." sentence largely restates them. The genuinely additive behavioral content is the requirement that MCP clients convert UTC starts_at/ends_at into the lodging timezone before display, which is real context not captured by annotations, though return shape and completeness are left unaddressed.

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?

Four short sentences with no repetition, though the first is a bare fragment and "Supports common list filters" is low-value filler that could be replaced with concrete filter behavior. Front-loading is acceptable but the purpose clause is the weakest part.

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 an output schema present, return values needn't be explained, and the timezone-display note covers client-side handling well. However, for a seven-parameter list tool the description says nothing about pagination/result limits, ordering, or the incremental-update behavior implied by updated_since and deleted filters.

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 all seven parameters, and the baseline is 3. The description adds nothing about the actual list parameters and never clarifies the schema's notable oddity that activity_type and transportation_type are marked 'only used by activities/transportations' — i.e., effectively inert for hostings.

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 the noun fragment "Hotel and lodging plans," which names the resource but never states the action (list/retrieve) or the scope (per-trip). The verb is only recoverable from the tool name and the sibling set (tripsy_hostings_create/show/update/delete) rather than from the text itself.

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?

"Supports common list filters" is the only usage statement and it is vague rather than directive. There is no guidance on when to use this versus tripsy_hostings_show for a single hosting, no note on whether results are paginated or complete, and no exclusions.

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?

The safety sentence ('Closed-world: operates within the authenticated user's Tripsy account') merely restates the supplied openWorldHint=false annotation rather than adding new information. The description says nothing about not-found behavior, required permissions, or what happens when trip_id and id mismatch, so beyond the annotations it contributes essentially nothing.

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, with the core action front-loaded and no filler. The safety clause is redundant boilerplate but does not obscure the purpose.

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?

This is a simple two-parameter read with an output schema, so return values need not be explained. However, the description omits not-found/error semantics and the need for both identifiers, leaving the definition only minimally adequate for correct invocation.

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 both trip_id and id are already documented in the schema. The description only echoes the 'by id' lookup and says nothing about the composite scoping (trip_id plus hosting id) or id formats, which is the baseline 3 when the schema 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 states a specific verb and resource: 'Fetch one Tripsy hosting by id.' That clearly separates it from the sibling list/create/update/delete operations on hostings. It does not explicitly name those siblings, so it falls short of a 5.

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?

There is no guidance on when to use this tool versus tripsy_hostings_list or the other hosting tools, and no mention that a trip_id scope is required to resolve the hosting. The agent must infer the retrieval use case purely from 'Fetch one ... by id.'

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?

The annotations already declare destructiveHint=true, openWorldHint=false, and idempotentHint=true, so the description's restatement of closed-world and destructive scoping adds limited new information. However, it does add genuinely new behavioral detail: only supplied fields are overwritten (implying a partial rather than full-replace update) and previous values are not automatically preserved or restored. It still doesn't describe error behavior for a bad id or permission requirements.

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, front-loaded with the action and resource, with no filler. The second sentence is a little heavy on restating annotation-declared properties (closed-world, destructive), but it stays compact and earns its place through the non-preservation detail.

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?

An output schema exists and parameter coverage is complete, so the description doesn't need to explain returns or argument shapes. For a mutation tool it covers the essential safety story (partial overwrite, no automatic restore, scoped to the authenticated account). The remaining gap is the accepted contents of the data object and the prerequisite of having a valid hosting id.

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 every parameter is already documented in the schema, and the baseline is 3. The description adds only the framing that 'data' contains the fields to be overwritten; it does not enumerate which hosting fields are accepted inside the nested, open-ended data object, which is the one place the schema leaves ambiguity.

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 states a specific verb and resource ('Update a Tripsy hosting') plus the keying mechanism ('by id'), which separates it from the create/delete/list/show siblings in the tripsy_hostings family. It stops short of naming an alternative tool or clarifying the relationship to tripsy_hostings_show for retrieving current values before overwriting.

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?

There is no explicit when-to-use or when-not-to-use guidance beyond the implied 'you have an id and want to change it'. It never says an id must first be obtained from tripsy_hostings_list or tripsy_hostings_show, nor when to prefer create over update. Usage is inferable from the verb and the name only.

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 destructiveHint=true and openWorldHint=false, so the safety framing ('Destructive', 'Closed-world') is largely redundant. However, the description adds genuinely new behavioral facts beyond the annotations: it clears parent associations (a cascade side effect) and the API reports success even when the email is missing or not owned by the caller — an idempotency/ownership nuance an agent cannot infer otherwise.

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, clearly separated sentences with the core action front-loaded and safety notes trailing. Minor waste in the 'Closed-world' sentence, which mostly restates openWorldHint=false already present in annotations.

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 destructive mutation with full annotation coverage and an output schema, the definition covers what an agent needs: what it deletes, the cascade effect, and the misleading success response. Only the absence of explicit when-to-use routing keeps it short of 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 a single parameter at 100% schema description coverage, the schema already explains that the id is an automation email id sourced from tripsy_inbox_list. The description adds no format, constraint, or validation detail beyond that, so 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 uses a specific verb and resource ('Delete an automation email owned by the authenticated user') and names a unique side effect ('clear its parent associations'). It is clearly distinguishable from siblings like tripsy_inbox_show and tripsy_inbox_update, though it never names those siblings explicitly.

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?

There is no explicit guidance on when to delete versus alternatives, or when not to delete. The only routing hint ('id from tripsy_inbox_list') lives in the schema, not the description, so an agent gets no usage-level instruction from the prose itself.

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 establish readOnly, idempotent, non-destructive, and closed-world behavior. The description still adds real value by disclosing that it returns all pages (no pagination controls needed) and by defining the exact email state being returned. It does not discuss ordering, volume, or what a failure/large mailbox looks like, so it is good but not exhaustive 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?

Front-loaded with the core action, then scope, then the next-step pointer — a good ordering with no filler sentences. The closing safety sentence largely restates openWorldHint=false, a minor redundancy.

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 an output schema present, the description need not explain return values, and it covers the essential facts: what is listed, what state those items are in, and the natural next call. Missing only finer operational detail such as ordering or expected volume for a potentially large inbox.

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 zero parameters, so per the rubric the baseline is 4. The description correctly implies there is nothing to configure, though it does not affirmatively say the caller need not supply filters.

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 uses a specific verb and resource ('List all pages of the authenticated user's inbound booking emails') and narrows scope with a state qualifier: emails 'not successfully parsed or attached to a trip, activity, hosting, or transportation.' That state definition is what separates it from the broader tripsy_emails_list, and it names tripsy_inbox_show as the read counterpart, so an agent can place it precisely among siblings.

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 clear context for use ('awaiting manual review') and an explicit follow-up path: 'Use tripsy_inbox_show to read the full email before processing it.' It does not state when NOT to use it (e.g., versus tripsy_emails_list for already-processed mail) or any prerequisites/limits, so it falls short of full alternative routing.

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 annotations, the description discloses that email content and attachments are untrusted data, not instructions, which is critical prompt-injection guidance. It also clarifies that body and attachment metadata are returned and that operation stays within the authenticated Tripsy account. The safety scope partly restates openWorldHint=false, but the trust-boundary warning adds meaningful behavior 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?

The description is front-loaded with the core read operation and return contents, then adds workflow and safety notes. It is generally efficient, though the reference to attachment metadata returned by the API is slightly redundant. No sentence is seriously out of 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?

Given the output schema, annotations, and single documented parameter, the description supplies the important missing context: untrusted content warning, downstream workflow, and safety scope. It is nearly complete for safe invocation. It could be stronger with explicit sibling differentiation from tripsy_emails_show, but no critical operational detail is missing.

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%, and the schema already documents that id is the automation email id from tripsy_inbox_list. The description does not add syntax, format, or validation guidance beyond the schema. With a single fully documented parameter, the baseline of 3 is appropriate.

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 states a specific verb and resource: read one automation email in full detail, including body and attachment metadata. It clearly distinguishes this from list/update operations and ties the email id to inbox listing. An agent can identify exactly what this tool returns without opening 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 clear workflow: use reservation details to create the appropriate itinerary item, then attach the email using tripsy_inbox_update. This tells the agent both the purpose and the likely next action. It does not explicitly mention when not to use it or how it differs from tripsy_emails_show, so it stops short of full alternative routing.

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?

The annotations already declare destructiveHint=true and openWorldHint=true, so the Safety block largely restates the supplied hints rather than revealing new behavior. It does add two genuinely non-obvious facts: a move clears prior parent associations and removes the email from the manual-review inbox, and the API may return an empty successful response. The remaining statements, such as not sending mail or modifying a provider mailbox, duplicate what openWorldHint already signals.

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 critical constraints (subject-or-one-target, exclusivity, inbox disappearance) are front-loaded and easy to scan. There is mild redundancy: 'Moves require exactly one editable target' repeats the earlier 'Supply subject or exactly one move target,' and the Safety block is wordier than the rest.

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 six-parameter mutation with an output schema present, everything an agent needs is covered: the target-exclusivity rule, the destructive side effects on prior associations, the visibility consequence, and even the empty-response caveat. No gap remains that would cause a mis-call.

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 each parameter is already documented, and the description wisely does not re-explain them one by one. It does add a cross-field constraint at the top level — 'do not supply trip_id alongside an item id' — that clarifies interaction between the move-target parameters, which is meaningfully beyond the per-field schema text.

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 verb pair and resource: rename a subject and/or move an automation email to a trip, activity, hosting, or transportation. That scope is concrete enough to separate it from the sibling read/delete tools (tripsy_inbox_list, tripsy_inbox_show, tripsy_inbox_delete) without inspecting 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?

It gives explicit call-shape rules: supply a subject or exactly one move target, and never combine trip_id with an item id. What is missing is direct routing to alternatives — it never says when to prefer tripsy_inbox_delete or an activities/transportations update instead — but the conditional constraints it does state are unambiguous.

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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is mostly carried by structured fields. The description's Safety sentence largely restates openWorldHint=false, though it does add useful specificity about the authenticated account and accessible trips, plus a hint that deletes are recoverable. It does not clarify whether the guidance is static text or scoped to a specific trip.

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 core purpose is front-loaded in the first clause, followed by a compact topic enumeration in a single sentence. It is dense but every listed topic corresponds to a real authoring rule (timestamps, covers, granularity, transfers, deletes), so little is wasted.

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 an output schema present, the description need not explain return values, and it covers the substantive topic areas an agent would need for trip authoring. Its main omission is workflow placement (when in relation to the create/update tools it should be consulted) and whether the guidance is static or trip-specific.

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 zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly implies a no-argument, reference-style call rather than hinting at inputs that the empty 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 uses a specific verb and resource combination ('Return concise agent guidance for creating high-quality Tripsy trips') and enumerates the topics covered (UTC timestamps, timezone display, Unsplash covers, granularity, coordinates, lodging, transportation, deletes). It is clearly a reference/guidance tool rather than a CRUD sibling, though it never names a sibling or says explicitly how it relates to trips_trips_create or the activities/hostings/transportations create tools.

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: the topic list (creation, timestamps, covers, lodging, transport) hints that it should be consulted before authoring trips or itinerary items, but there is no explicit 'call this before X' directive or exclusion of when not to call it. An agent must infer the workflow position from the topic list alone.

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?

The annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds that the tool operates within the authenticated account and accessible trips, but this largely restates the closed-world annotation and does not add much beyond it.

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 short and front-loaded with the core action. The safety sentence is somewhat redundant with the annotations, but it does not make the definition verbose.

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 zero-parameter read-only tool with rich annotations and an output schema, the description is complete enough. It identifies the returned resource and the account scope without needing to explain return values, which the output schema covers.

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 has zero parameters, so there is no parameter semantics burden. The description appropriately does not discuss parameters, and the baseline for a no-parameter tool is 4.

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 states a specific verb and resource: 'Return the authenticated Tripsy profile.' This clearly distinguishes it from the sibling update tool, tripsy_me_update, though it does not explicitly name that alternative.

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 implied by the purpose: fetch the current authenticated user's profile. There is no explicit when-to-use guidance, no exclusions, and no mention of alternatives such as tripsy_status.

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 destructiveHint=true, openWorldHint=false, and idempotentHint=true, so the description's "closed-world" and "destructive" lines largely restate structured data. It does add one genuinely new behavior — that only supplied fields are overwritten and prior values are not preserved or restored — which clarifies partial-update semantics beyond the booleans, but says nothing about auth requirements beyond the generic account scope or about how unknown fields are handled.

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 with the purpose front-loaded and a labeled Safety section, so it scans quickly. Some space is spent re-asserting annotation facts (closed-world, destructive) rather than adding new information, which keeps it from a 5.

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?

An output schema exists so return values need not be described, and the destructive/partial-overwrite warning is covered. However, for a mutation tool wrapping a free-form nested "data" object with additionalProperties=true, the description should say whether unspecified fields are left untouched versus reset, and what the valid field set actually is beyond four examples.

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 nominally 100%, but the schema only says "data: object of Tripsy API fields to send" with additionalProperties=true and never names a single field. The description is therefore the sole source of field semantics, listing name, timezone, language, and default currency as valid keys, which is real added meaning over the 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 description gives a specific verb and resource ("Update current Tripsy profile fields") and enumerates example fields (name, timezone, language, default currency), which clearly separates it from the trips_*/expenses_* update tools. It stops short of naming the natural sibling tripsy_me_show as the read counterpart, so sibling differentiation is implied rather than explicit.

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 implied by "update current profile" — an agent can infer this is the tool for changing one's own account settings — but there is no explicit when-to-use/when-not, no mention of tripsy_me_show for reading current values before changing them, and no stated prerequisites.

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 bar is low. The description's genuine addition is the assurance that the stored token is never revealed, which is real behavioral context beyond the annotations; the closed-world sentence largely restates openWorldHint=false.

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 purpose, with no padding. The 'Safety: Closed-world...' clause partially duplicates the openWorldHint=false annotation, which costs a little.

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 an output schema present, rich annotations, no required parameters, and full schema coverage, the description only needs to state scope and any safety caveat — both are present. Do not need to discuss return format.

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 single optional parameter is fully documented in the schema (100% coverage), including the 'when true and authenticated' condition. The description adds no further meaning about it, so 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?

Names a specific verb ('Inspect') and resource ('Tripsy MCP configuration and authentication state'), which is clearly separable from the CRUD siblings. It does not explicitly name the nearest sibling (tripsy_me_show) as an alternative, but the configuration/auth-state 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 pre-flight/auth-check tool, reinforced by the parameter note 'when true and authenticated'. There is no explicit when-to-use, when-not-to-use, or named alternative among the ~50 sibling tools.

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 this is a non-read-only, non-destructive, closed-world write, so the 'Safety: Closed-world' sentence and timezone-normalization contract add only modest context. Genuinely useful disclosures are the UTC-always storage rule and the requirement that clients convert timestamps before display, but conflicts, validation failures, and side effects on itinerary ordering are not described.

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 critical scope sentence is front-loaded, but the body repeats the full 12-slug list and label mapping twice more even though the enum and schema descriptions already list them identically. Roughly a third of the text is redundant with structured fields and could be cut without losing 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?

For a 24-parameter create tool with an output schema and annotations already present, the description covers the domain conventions an agent needs: timezone handling, type slugs, flight and transfer special cases, and code-vs-number field choice. Missing are error behavior and the relationship of optional top-level fields to the raw 'data' merge field, which is only explained in the schema.

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% and the schema descriptions already carry the flight IATA convention, the provider_reservation_code vs transport_number split, and the timezone conversion notes verbatim. The description's only real addition is bundling these into a cross-field flight/transfer workflow, which is helpful but duplicates structured data almost sentence for sentence.

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 states a specific verb and resource: 'Create a Tripsy transportation for point-to-point movement,' which is enough to distinguish this from the list/show/update/delete siblings by name and intent. It stops short of explicitly contrasting itself with trips_transportations_update, but the operation is unambiguous.

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 concrete when-to-use rules for the main branches: use transportation_type airplane for flights, transfer for transfer activities with both endpoints filled in, and omit name for flights unless the user supplied one. It offers no guidance on create vs. update, on required trip preconditions, or on what to do if the trip_id is invalid.

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 destructiveHint=true and openWorldHint=false, and the description's 'Safety' block largely restates those same facts rather than adding new information. It says nothing about whether the deletion is permanent or recoverable, whether it cascades to related records, or what happens when the id does not exist — the details an agent actually needs before invoking a destructive call.

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 short and front-loads the core action before the safety notes, so an agent gets the essential fact immediately. The safety block is somewhat boilerplate and partially redundant with the annotations, keeping it from a 5.

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?

An output schema exists, so return values need not be explained, and the two-parameter schema is fully documented. However, for an irreversible delete the description omits permanence, cascade behavior, and error conditions, leaving meaningful gaps for a destructive tool.

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 both trip_id and id are documented in the schema, establishing the baseline of 3. The description's 'by id' phrasing adds nothing about the required trip_id/id relationship or id format beyond what the schema already provides.

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 verb and resource ('Delete a Tripsy transportation by id'), which is unambiguous and matches the tool name. It is clearly distinguishable from siblings like tripsy_transportations_update or tripsy_transportations_show by the delete verb, though it never names those siblings explicitly.

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?

There is no guidance on when to use this tool versus alternatives, no prerequisites (e.g., ownership or collaborator permission needed to delete), and no note about confirming intent before calling. The only implied usage comes from the word 'Delete' in the first sentence.

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