travelMCP Directory

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

The description is consistent with the readOnlyHint and openWorldHint annotations, and it adds useful context about what the response contains. It does not mention missing-slug behavior or formatting, but the annotations already communicate that this is a safe read operation.

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 concise sentences with no filler: the first states the core action and return contents, the second gives the operational prerequisite. Everything earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read-only retrieval tool, the definition is largely complete: it identifies the resource, the slug source, and the main response components. It lacks an explicit not-found response description, but this is a minor gap given the simple scope and existing annotations.

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

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

The schema fully documents the slug parameter with an example, so the baseline is 3. The description adds extra value by explaining that valid slugs come from search_travel_tools, which gives the agent operational grounding 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 description names a specific operation ('Fetch one directory listing by slug') and the exact contents returned (full description, install snippet, setup documentation). It also distinguishes this tool from its siblings by pointing to search_travel_tools as the source of the slug.

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 slug returned by search_travel_tools' provides clear when-to-use guidance by tying this tool to a preceding search call. It does not explicitly contrast with list_categories, but for a simple retrieval follow-up step the usage context is clear enough.

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 and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral detail: it returns slug and listing count per category and marks travel-specific categories as pinned. This goes beyond the annotations without contradicting them.

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

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

Two sentences with no fluff. The main action and scope are front-loaded, followed by the useful pinned-category detail. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only listing tool, the description is fully sufficient. It explains what is returned (every category, slug, listing count, pinned status), and no output schema exists to cover this. No critical 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?

The input schema has zero parameters, so parameter semantics are largely not applicable. The baseline for a zero-parameter tool is 4, and the description appropriately focuses on return values instead of parameters.

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 every category in the directory' with its slug and listing count. It also clarifies the pinned marking for travel-specific categories, making the tool's scope and output clear. This differentiates it from siblings like search_travel_tools and get_tool_details.

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 a broad browsing use case—listing all categories—but does not explicitly state when to prefer this over search_travel_tools or get_tool_details. Sibling names provide some contextual differentiation, but no explicit when-to-use versus alternatives is given.

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 and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context beyond the annotations: typo-tolerant full-text search and the specific result fields returned. There is no contradiction with 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?

The description is two compact sentences with no wasted words. It front-loads the action and resource, then adds return shape and matching behavior without repeating schema details.

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 all-optional 4-parameter tool with no output schema, the description plus schema adequately cover invocation and result contents. It could clarify behavior when query is omitted or how pagination works, but limit defaults are in the schema and the return fields are stated.

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 each parameter is already documented, including the enum for type and examples for query and category. The description reinforces query semantics with 'typo-tolerant full-text search' but does not need to compensate for missing schema details.

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: 'Search the OmniTravel directory of MCP servers, agent skills and APIs for travel technology.' It also lists the returned fields (tagline, category, author, URL), which clearly differentiates it from the sibling tools get_tool_details and list_categories.

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 establishes this tool as the directory's search entry point and the optional type/category/limit filters in the schema clarify scoping. It does not explicitly name when not to use it or mention sibling alternatives, but the search-focused context is clear and no prerequisites are needed.

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