TrekkSoft MCP by usefulapi

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

The readOnlyHint annotation already establishes this as a safe read, so the description only needs to add context. It contributes the endpoint mapping (GET /activities/{activityId}) and the shape of the payload, but says nothing about error behavior for a missing id, auth requirements, or whether nested sub-resources are expanded.

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 compact sentences, zero filler, with the core verb-and-resource statement front-loaded before the return contents and endpoint reference.

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?

There is no output schema, so naming the returned fields serves as the return-value sketch, and the endpoint reference anchors it in the API. Only edge-case behavior (missing activity, permissions) is absent, which is minor for a simple read.

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%, with both activity_id and the language default documented in the schema itself. The description adds only 'by id' and repeats nothing about the language parameter, 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 ('Get one activity by id') and enumerates what is returned (description, schedule, price categories, settings). This distinguishes it from list-style siblings like trekksoft_list_activities, though the contrast is only implicit in the word 'one'.

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 'by id' phrasing implies this is the detail-fetch follow-up to a list call, and the schema notes the id comes from trekksoft_list_activities. However, the description itself gives no explicit when-to-use or when-not guidance versus the sibling list/get 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?

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds the underlying HTTP endpoint and lists the data fields returned, which is useful, but it does not discuss error behavior, authentication, rate limits, or pagination.

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 compact sentences with the core action and returned data front-loaded. Every phrase contributes useful information, and there is no redundant or vague 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?

For a simple single-parameter read tool with no output schema, the description provides sufficient context by naming the resource, lookup key, and key returned fields. It could optionally mention not-found behavior, but no critical calling information 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 the single booking_id parameter is already well documented in the schema. The description adds only 'by id' and does not expand on format or sourcing beyond what the schema field description 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?

The description names a specific verb and resource: 'Get one booking by id.' It also enumerates the main returned fields (activity, guests, prices, payments, status), making the tool's scope clear and distinguishing it from list-style siblings, though it does not explicitly name a sibling 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?

The phrase 'by id' implies the tool should be used when a booking id is already known, but the description offers no explicit when-to-use guidance or comparison with trekksoft_list_bookings. The useful note that the id comes from trekksoft_list_bookings appears only in the schema, not the description.

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, so the safety profile is covered. The description adds real value by disclosing that the response includes the booking link and check-in state, but says nothing about error behavior (e.g., unknown id) or what happens for guests with no booking.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the action and resource, with the endpoint appended as a compact technical footnote. No filler or 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 no output schema, the description carries some burden for return values and it names two useful fields, but a full guest object likely has more fields and possible 404 behavior that remain undisclosed. Adequate but not complete for a record-fetch 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% and the single guest_id parameter is fully documented, including its provenance. The description restates only 'by id' and adds no format or derivation detail beyond the schema, 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 ('Get one guest by id') plus the notable payload contents (booking link, check-in state) and the underlying endpoint. It implicitly distinguishes itself from trekksoft_list_guests by the singular/by-id scope, though it never names the sibling 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?

Usage is only implied: 'by id' signals a single-record fetch after an id is known, and the schema (not the description) points to trekksoft_list_guests as the id source. No explicit when-to-use or when-to-prefer-a-list statement appears in the description.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's burden is lower. It usefully discloses the backing endpoint (GET /activities) and that filters are applied server-side, but says nothing about pagination behavior or volume limits, which matter for a 9-parameter list tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences: purpose and filters first, endpoint second. No filler 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 read-only, zero-required-parameter list tool with fully documented schema and readOnlyHint coverage, the description gives enough to call it correctly. The only real gap is the absence of any hint about paginated results or how it relates to trekksoft_get_activity / trekksoft_list_activity_availabilities.

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 is already documented in the schema. The description surfaces the filter semantics (merchant, category, title, active, bookable) but omits id, language, limit and offset, adding no meaning beyond the schema — 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 (list tours/activities) plus the scope of filters and the underlying API call (GET /activities). The list-vs-get distinction from siblings like trekksoft_get_activity is inferable from the name and verb, but 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?

The filter list implies usage (browse/filter activities by merchant, category, title, active/bookable state) but there is no explicit when-to-use guidance, no exclusion, and no pointer to trekksoft_get_activity for single-record retrieval. Usage must be inferred.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds scope ('free seats'), but that framing is somewhat at odds with the only_booked/only_not_booked filters, which suggest departures without free seats can also be returned. It says nothing about pagination behavior despite limit/offset existing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the resource and scope; nothing is wasted. The API endpoint is marginally redundant for an agent but reinforces the underlying contract, so only a small deduction.

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 an 11-parameter read tool with no output schema, the description never indicates what an availability record contains (departure time, seats, booking state), which would help the agent interpret results. Annotations cover the safety profile and the schema covers inputs, so this is the main remaining gap but it is a real one.

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 11 parameters (date bounds, seats minimum, language, booking filters, paging) are already documented in the schema. The description adds no syntax, defaults, or interaction rules (e.g., that only_booked and only_not_booked are mutually exclusive), 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?

States a specific verb and resource ('list departures ... for one activity') and grounds it in a concrete API endpoint, so the agent knows exactly what is being fetched. It does not name or differentiate itself from the sibling trekksoft_list_availabilities (the cross-activity variant), leaving that distinction to inference from 'one activity'.

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: 'for one activity' suggests this is the single-activity counterpart to the broader list tool, and the required activity_id makes the prerequisite obvious. There is no explicit when-to-use / when-not guidance and no mention of trekksoft_list_availabilities as the alternative when no activity is chosen.

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?

readOnlyHint=true already declares the safety profile, so the description only needs incremental context. It adds the date-range scoping and names the underlying endpoint, but says nothing about pagination behavior, defaults, or how the 'free seats' framing interacts with the only_booked/only_not_booked filters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the core behavior. The API endpoint reference earns little for an agent but costs only a 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?

With 13 optional parameters, no output schema, and no annotation beyond read-only, the description leaves return shape, pagination, and default filtering unexplained. The 'free seats' framing is also potentially misleading given only_booked and only_not_booked filters exist.

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 13 parameters are already documented in the schema. The description only echoes the date-range and seat concepts, adding no format, default, or interaction detail beyond the schema; 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: listing departures with free seats across activities within a date range. It is clear what the tool returns, though it does not differentiate itself from the sibling trekksoft_list_activity_availabilities.

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 trekksoft_list_activity_availabilities or the activity endpoints, and no stated prerequisites or exclusions. The agent must infer selection from the name 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?

readOnlyHint=true already establishes the safety profile, so the description is not carrying that burden. It adds only the upstream endpoint reference (GET /bookings) and the vague 'recent' scoping hint; it says nothing about default ordering, whether cancelled bookings are included, or how many results a caller should expect before paging.

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 scope, followed by the filter surface. The trailing 'TrekkSoft API: GET /bookings' is marginal but cheap and aids API mapping; nothing else 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?

All 10 parameters are self-documented and the read-only annotation covers safety, but with no output schema the description should say more about what a result row contains, pagination totals, and default sort/recency window. For a 10-param list endpoint that is a noticeable gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description's filter list maps almost one-to-one onto parameters already documented in the schema and adds no formats, defaults, or interaction rules (e.g. how q combines with user or merchant) beyond what the schema states.

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?

Specific verb+resource ('List recent bookings') with an enumerated set of supported filters, which clearly separates it from the singular trekksoft_get_booking sibling. The qualifier 'recent' is left undefined, so the retrieval scope is imprecise.

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 list of filter dimensions implies when the tool is appropriate (browsing/searching bookings), and the presence of q/user/merchant hints at broadening-narrowing usage. However, it never states when to prefer trekksoft_get_booking for a single record, nor any exclusion or prerequisite such as required merchant scoping.

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?

readOnlyHint=true already declares the safety profile, so the description only needs to add context. It contributes the underlying API endpoint (GET /guests) and the filterable dimensions, but says nothing about default paging behavior, maximum page size, or what a result row contains — details the annotations don't 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?

Two short sentences, front-loaded with the action and resource, then the filter axes. The API endpoint citation is marginally useful but adds little for an agent that already has the tool name.

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 9-parameter read-only list tool with no output schema, the description should say something about what comes back (guest objects? pagination envelope?). It covers the input side adequately but leaves the return shape entirely unspecified, which is a real gap given the absence of an output 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 description coverage is 100%, so every parameter is already documented in structured data. The description merely summarizes the same filter categories (booking, departure, phone, name, cancellation) and omits the id, limit and offset parameters entirely, adding 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?

States a specific verb+resource ('List guests (participants)') plus the filter axes, which separates it from trekksoft_get_guest and the other list_* siblings. It stops short of explicitly naming 'get_guest' as the single-record alternative, so the differentiation is inferable 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?

The presence of filters implies when to reach for this tool (bulk/lookup with criteria vs. fetching one guest), but there is no explicit when-to-use/when-not statement and no mention of the trekksoft_get_guest alternative. Usage must be inferred from the parameter list.

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, so the safety profile is covered. The description adds useful context that results are credential-scoped, but says nothing about pagination, result ordering, or the shape of returned merchant objects, which a listing tool would normally disclose.

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 zero filler; the scope constraint is front-loaded and the endpoint reference is compact and useful for traceability.

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?

A zero-required-parameter read-only listing tool with fully documented params and annotation-covered safety does not need much more. The only residual gap is that no output schema exists and the description does not hint at what merchant fields come back.

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% — id, slug, and language are all documented in the schema. The description adds no meaning beyond the schema (e.g., whether id and slug combine as AND or OR filters), 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 the merchants") plus the scope constraint ("your key pair can access"), and the underlying endpoint GET /merchants confirms it. The merchant resource is naturally distinct from the sibling tools (bookings, guests, activities, shop items), so no explicit sibling routing is needed.

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 "your key pair can access" implies this is a discovery/listing call scoped to credentials, but the description never says when to call it versus filtering another listing or when-not to call it. Usage is inferable from the name and scope clause rather than stated.

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?

readOnlyHint=true already tells the agent this is a safe read, and the description adds the backing endpoint (GET /shop/items), which is minor but real context. It says nothing about pagination, result caps, or whether inactive items are returned by default—behavioral facts an agent would want before calling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the purpose and the clarifying gloss before the ancillary endpoint reference. Nothing is padded, though the trailing API endpoint line is of marginal value to an agent.

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-required-param, read-only list tool with full schema coverage and annotations covering the safety profile, the description is sufficient to select and call it. The only real gap is that no output schema exists and the description doesn't hint at the shape of the returned list.

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 all five parameters including their array semantics. The description restates the merchant/category/active filters but adds no meaning beyond them and omits the id and language params entirely. 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 ('List shop items') and clarifies the domain term with a gloss ('extras sold with activities'), which an agent couldn't infer from the name. It also names the filter dimensions. It does not explicitly distinguish itself from the list_activities/list_merchants siblings, so it stops 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?

'Filterable by merchant, category and active state' implies the retrieval use case but never states when to reach for this tool versus a sibling list_* or a get_* lookup. There are no exclusions or prerequisites, leaving usage to inference.

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