concierge

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool 'requires a bearer token' which implies authentication needs. However, it does not disclose what side effects occur (e.g., does it overwrite existing activities?), what happens on conflict, or how the response behaves (since there is no output schema). The mutation intent is clear, but missing important behavioral traits.

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 a single sentence that front-loads the primary purpose. It is efficient and uses 25 words to convey the core action, slot options, and optional linking. Every clause 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?

Given the complexity of 8 parameters (4 required), no output schema, and no annotations, the description is incomplete. It does not explain what happens to existing activities in the same slot, what the return value is, or how the optional linking parameters interact (e.g., if one is provided, must the other be as well?). The tool has many siblings, and the description does not sufficiently differentiate 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?

Schema description coverage is 63%, so the description already covers some parameter meaning (slot options, optional content linking). The description repeats the slot values from the enum but does not explain the 'wp_content_type' semantics beyond what the schema provides. For 8 parameters, it adds modest value 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 clearly states the action ('Add an activity'), the target ('to a specific day and time slot'), and specifies the slot options ('morning/afternoon/evening'). It also mentions an optional capability to link to content. It distinguishes from related tools like 'add_day' or 'create_itinerary', though it could be more explicit about how it differs from 'write_itinerary_day_detail'.

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 for adding activities to days, but does not provide guidance on when to use this tool versus alternatives like 'write_itinerary_day_detail' or when not to use it. No exclusions or prerequisites are mentioned (beyond the bearer token).

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

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

No annotations are provided, so the description carries the full burden. It only reveals the side effect of incrementing num_days and the auth requirement, but omits many behavioral traits: whether the operation is reversible, what happens if the itinerary_id is invalid, whether it mutates other state, or any response format. For a mutation tool with zero annotations, this is insufficient.

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 a single concise sentence that communicates the primary action and a key side effect, with no extraneous information. However, it could be restructured to front-load the required auth context more clearly.

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 tool has no output schema, no annotations, and 3 parameters with low schema coverage, the description leaves significant gaps. It does not state what the operation returns (e.g., the updated itinerary object), error conditions (e.g., missing itinerary), or any rate limits. For a tool that mutates state (incrementing num_days), these are critical missing details.

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 low (33%), but the description does not add any parameter-specific details beyond what the partial schema provides. The tool name, title, and schema already convey that itinerary_id is required and that title is optional. The description does not explain the notes parameter at all, nor does it clarify the relationship between notes and title. Since the description fails to compensate for the low schema coverage, it merits a baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('append an extra day') and the resource ('concierge itinerary'), and mentions a specific side effect ('increment num_days'). It distinguishes itself from sibling tools like add_activity and write_itinerary_day_detail by focusing on adding a day rather than adding an activity or writing day 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 mentions a prerequisite ('requires a bearer token') but does not specify when to use this tool versus alternatives like create_itinerary or update_itinerary. There is no guidance on when not to use it, such as if the itinerary already has a maximum number of days or if the user only wants to modify an existing day.

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

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

With no annotations provided, the description covers key behaviors: auth requirement (bearer token), public visibility, auto-created days, and share-link return. However, it omits side effects, reversibility, or consequences of creation, which is adequate but not rich.

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 core purpose and key behaviors. No wordiness. Slight improvement possible by merging the auth requirement into the first sentence, but already efficient.

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

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

Given no output schema and no annotations, the description partially covers response (share link) and auto-created days. Missing details on return structure, error behavior, and prerequisites beyond bearer token. Adequate but not comprehensive for a creation 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 the baseline is 3. The description adds no additional meaning beyond the schema: 'optional ISO date string' and 'optional short description' are already present. No parameter-value enrichment (e.g., constraints or examples) beyond what's in 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 uses a specific verb ('Create') and resource ('itinerary'), qualifying it as 'empty' and attributing to the concierge. It distinguishes clearly from sibling tools like update_itinerary (modify existing) and generate_itinerary_from_places (from places).

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 'use when starting from scratch' via 'empty' and notes that days are created automatically, but lacks explicit when-not or alternatives. No comparison to sibling tools like add_activity or generate_itinerary_from_places.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It correctly indicates this is a destructive operation ('Remove...activity') and notes the authentication requirement ('Requires a bearer token'), which is critical for agent invocation. It could additionally mention irreversibility or side effects on the itinerary, but the current disclosure is still good.

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 only two sentences, front-loading the action and resource, then immediately providing the critical requirement. Every sentence earns its place with no wasted words.

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 low complexity (1 parameter, no output schema, no nested objects), the description covers the essential aspects: action, resource, and auth requirement. It does not explain return values, but there is no output schema to detail them, and for a deletion operation the return is typically minimal. A brief note on what happens upon success (e.g., 'no return content') would make it complete, but the current state is still nearly 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?

The single parameter activity_id is fully defined in the schema with type, format, and pattern, providing high structural clarity. However, schema description coverage is 0%, meaning the schema property has no description field. The tool description does not elaborate on activity_id any further, so it adds no meaning beyond what the schema already provides. 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 uses the specific verb 'Remove' with the resource 'activity from a concierge itinerary day', making the action and scope clear. It distinguishes this tool from siblings like delete_itinerary, which operates on a different resource.

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 states a prerequisite ('Requires a bearer token'), but provides no guidance on when to use this tool versus alternatives (e.g., update_itinerary or write_itinerary_day_detail). Sibling tools suggest possible alternatives for modifying itineraries, but the description does not address 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 description discloses the destructive nature ('permanently delete') and cascade behavior (days and activities), and mentions authentication ('requires bearer token'). However, with no annotations, it lacks details on irreversibility confirmation, side effects on bookings, or prerequisites beyond the token.

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 very concise with two sentences, front-loading the key action and scope. Every sentence adds value without 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?

Given the simple parameter (one required UUID), no output schema, and zero annotations, the description covers the essential action and cascade but omits prerequisites (e.g., itinerary must exist, user ownership) and return behavior, making it adequate but not thorough.

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 0%, so the description should explain the parameter. It does not mention itinerary_id, its format (UUID), or how to obtain it. The description adds no semantic value beyond the schema, leaving the agent to infer from context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('delete'), the resource ('concierge itinerary'), and the scope ('all its days and activities'), which distinguishes it from siblings like delete_activity that delete a single 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?

No guidance is provided on when to use this tool versus alternatives (e.g., update_itinerary for modifications, delete_activity for single entries). The description only states what the tool does, not when to prefer it.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses key behaviors: the tool is asynchronous (returns immediately with an ID, requires polling get_itinerary), it creates original plans (never copies), and it's attributed to a specific account and made public. The generation progress states are provided. This is strong transparency.

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 a single, focused paragraph that front-loads the core action and input requirements. It efficiently packs behavioral notes (asynchronous, originality, attribution) and output expectations. A minor reward could be given for structuring into logical clauses, but it could be slightly more terse.

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 tool's complexity (5 params, async with polling, no output schema), the description covers the essential interaction flow: inputs -> immediate response -> polling mechanism. It doesn't need to explain return values since get_itinerary (a sibling) likely covers the output schema, but it could explicitly mention that the returned share link is part of the immediate response.

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 adds value by clarifying the 'places' parameter's usage ('at least 3'), explaining what 'preferences' means ('pace, interests, budget, travel style'), and that 'language' uses a three-letter code. This provides context beyond the schema field 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?

The description clearly states the tool's purpose: given user places and preferences, it builds a bespoke itinerary. It uses specific verbs ('builds,' 'mines,' 'synthesizes') and distinguishes itself from siblings like 'create_itinerary' (which likely creates an empty shell) and 'update_itinerary'.

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 explains when to use the tool: when the user has at least 3 places and optional preferences. It doesn't explicitly say when not to use it or compare to 'get_itinerary', but the context of building vs. polling is implied. Requires a bearer token usage context is mentioned.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal the cache chain traversal and the inclusion of a `source` field in the return. However, it does not address error behavior (e.g., what happens if the item is not found), authentication needs, or idempotency. For a read operation, the absence of error clarity is a notable gap.

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 extremely concise, consisting of only two short sentences. The first sentence front-loads the action (Fetch a single content item) and key parameters, while the second adds the return behavior. Every phrase earns its place with no redundancy or 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?

Given the simplicity of the tool (two parameters, single-item fetch) and the absence of an output schema, the description covers core functionality and adds useful context about the cache chain and return field. However, it does not explain error states, the relationship to sibling tools that may appear to overlap, or the full return shape. It is adequate but not fully comprehensive.

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 provides a description for the `id` parameter but not for `type`. The description mentions both parameters without adding detail about the `type` enum values or constraints. With schema description coverage at 50%, the description should compensate for the missing schema descriptions but does not sufficiently elaborate on parameter semantics beyond what is already present.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches a single content item by type and id, with specific behavior of walking the content chain (WordPress -> cache). However, it does not differentiate from sibling tools like get_destination or get_itinerary, which likely serve similar purposes for specific types, potentially causing confusion about when to use this generic getter.

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 provides no guidance on when to use this tool versus the similar sibling tools get_destination, get_itinerary, or search_content. It also fails to mention any prerequisites, context, or conditions under which this tool should be chosen over alternatives. This leaves the agent without decision-making support.

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

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

No annotations are provided, so the description carries the burden of disclosing behavior. It mentions that it takes a slug or id and returns full details, but doesn't disclose what happens if not found, error handling, or any side effects. Since it's a read operation, this is less critical, but the lack of any behavioral context beyond the basic operation is a gap.

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 a single, concise sentence that directly states the tool's function and parameter options. No unnecessary words 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?

Given the simplicity (1 parameter, no output schema, no annotations) the description is minimally sufficient. It identifies the tool's purpose and parameter usage, but lacks context on the return format or typical use cases. For a simple read tool, this is acceptable but not outstanding.

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 parameter is fully documented in the schema. The description adds 'full details' but does not specify what those details include beyond what the tool name implies. Baseline 3 is appropriate since the schema handles 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 description clearly states the tool's purpose: getting full details for a single destination by slug or id. It distinguishes from siblings like list_destinations (plural) and other get_* tools, though it doesn't explicitly name the 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?

It implies usage for retrieving a single destination, as opposed to list_destinations for multiple, but does not explicitly state when to use this over other retrieval tools. No exclusions or alternative tools are mentioned.

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

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

No annotations are provided, so the description carries the full burden. It discloses that public itineraries are readable without a token and private ones require the owning token, which is an important authentication behavior. It also states the sorting order. For a simple read operation, this is sufficient behavioral insight.

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 extremely concise at two sentences. The first sentence front-loads the core action and output structure; the second adds essential auth context. Every word contributes value with no 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 single-parameter read tool with no output schema, the description fully covers what the tool returns (full itinerary with days and activities sorted) and its access behavior (token requirements). There are no missing details needed by an AI agent to use this tool 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?

The input schema has only one parameter (itinerary_id) with 100% description coverage in the schema (it describes it as 'The UUID of the itinerary'). The description adds no additional meaning or usage guidance for this parameter, so it meets the baseline of 3 for high schema coverage.

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 the specific verb 'Get' with the resource 'full itinerary with all days and activities', and adds sorting detail ('sorted by day number and time slot'). This clearly distinguishes it from sibling tools like 'list_itineraries' (which lists summaries) and 'get_content' (different resource type).

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 provides context on when to use (retrieve full itinerary) and mentions token requirements for public vs private itineraries. However, it does not explicitly state when NOT to use it or offer direct alternatives among the many sibling tools, such as noting that 'list_itineraries' is for getting a list of itinerary IDs.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool is public (no auth), that it returns nulls for absent blocks, and that older itineraries have none of them. This is valuable behavioral context for an agent. The description could be slightly richer (e.g., clarifying if nin is idempotent or if there are rate limits), but for a read-only tool with no annotations, this is well above average.

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 three sentences long with no filler. The first sentence front-loads the purpose and contents, the second adds auth context, and the third explains the return behavior. 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 tool with no output schema and only one simple parameter, the description covers the key aspects: what it reads, what it returns (with nulls for missing blocks and note on older itineraries), and auth requirements. It doesn't explain pagination, size limits, or error conditions, but for a single-object read with an implied one-to-one mapping, this is sufficient.

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 only one parameter (itinerary_id) and schema description coverage is 0%, so the description must compensate. The description states that the tool reads an itinerary's dossier and implies that the input is the itinerary identifier. While it doesn't elaborate on the UUID format (the schema does that), it adds essential context about what the parameter identifies and what the output relates to, which is sufficient for an agent to infer the parameter's 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 description explicitly states the verb 'Read' and specifies the resource 'itinerary's planning dossier', then itemizes the contents (legs, seasonality, cost model, booking order, field notes, open choices). This clearly distinguishes it from sibling tools like 'get_itinerary' (which likely returns a simpler overview) and 'set_itinerary_dossier' (which writes).

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 says 'Public — no token needed', which is a clear usage precondition. It also notes that older itineraries return nulls for blocks, implying this tool is appropriate for retrieving detailed planning data. However, it does not explicitly state when to choose this over alternatives like 'get_itinerary' or 'get_pricing', nor does it mention any exclusions for using it on itineraries that lack the dossier.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It states the tool is 'read-only and public', which conveys it has no side effects and requires no authentication. This is good transparency for a simple list operation, though it lacks details like response format or potential error cases.

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 sentences with no wasted words. It front-loads the verb 'List' and immediately defines the scope. Every sentence adds value, and the structure is optimal.

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 tool with no parameters and no output schema, the description is mostly complete. It explains what the tool does, when to use it, and that it's safe to call. It could optionally detail the exact return structure, but the mention of 'tiers and their prices' is sufficient for an AI agent to understand the output.

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 and schema coverage is 100% (trivially). The baseline for 0 parameters is 4, and the description does not need to add parameter information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists paid concierge service tiers and their prices, with specific examples of the three tiers. It distinguishes itself from sibling tools like price_itinerary by specifying it covers service tiers rather than pricing a specific itinerary.

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 provides clear usage context: 'use this to quote a traveller before they buy.' It implies this is the appropriate tool for pre-purchase pricing. However, it does not explicitly mention when not to use it or list alternative tools (e.g., price_itinerary for post-selection pricing).

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

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

No annotations provided. The description only says it is an alias, implying identical behavior to get_content but discloses nothing about that behavior (e.g. read-only or destructive). For a tool with zero annotation coverage, the description should at least hint at whether it isa read or mutation operation. Here it does not, so transparency is minimal.

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?

Exactly one sentence with no filler. All information is front-loaded. Every word earns its place. Perfectly concise for an alias definition.

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 simplicity (alias tool with 2 parameters, no output schema), the description is sufficient for its purpose: it tells the agent to use get_content instead. It relies on get_content’s description for full details, which is acceptable for an alias. Minor deduction: if get_content description is poore, completeness suffers, but evaluating this tool alone it is complete enough.

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 50% description coverage (only id’s description exist). The description adds zero additional meaning about parameters – it does not explain type’s enum values or id’s usage beyond what schema already states. With low coverage, the description should compensate but does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as an alias of get_content, using specific language ('Alias of get_content'). It distinguishes purpose from siblings by naming the preferred tool, though it does not describe what get_content does. The purpose is clear for an alias but relies on sibling tool description for full meaning.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states 'Prefer get_content', giving direct guidance on when to use this tool vs. the alternative. The agent knows this tool is only for backwards compatibility. No other exclusions 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?

With no annotations, the description must disclose behavioral traits. It indicates a read operation but does not mention side effects, authentication, rate limits, pagination, or the return format. The limit parameter hints at pagination, but it is not explained. The agent is left guessing about behavior.

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 a single, concise sentence that is front-loaded with the verb and resource. It contains no superfluous words, making it efficient. However, it sacrifices some completeness, which prevents a perfect score.

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 tool's simplicity (3 optional params, no output schema), the description is minimally adequate. It states what the tool does and mentions filters, but lacks details on return values, pagination, or defaults. It is complete enough for a basic understanding but could be improved.

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 67% (region and category have descriptions, limit does not). The description adds no new meaning beyond the schema: it merely repeats 'filtered by region or category'. It does not explain the limit parameter or provide examples, so it fails to compensate for the missing schema description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'list', the resource 'destinations', and the scope 'from the database, optionally filtered by region or category'. This is specific and distinguishes from sibling tools like get_destination (single) and list_itineraries (different resource).

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 is provided on when to use this tool versus the many siblings. It does not explain that it is for browsing all destinations, while get_destination is for a specific one, or that other tools handle itinerary management. The description only mentions optional filtering without any contextual advice.

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

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It mentions the need for a bearer token (authentication) and implies a read-only list operation, but does not explain whether this returns full itinerary objects or summaries, whether it has pagination or limits, or any rate limits. For a listing tool with no annotations, this is insufficient transparency.

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 a single, front-loaded sentence that conveys the purpose, scope, ordering, and authentication requirement. Every element earns its place, with no wasted words. It is optimally concise for the information it provides.

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 tool with 0 parameters, no output schema, and no annotations, the description is minimally adequate. It covers the basic purpose and an important requirement (bearer token). However, it does not describe the output format or any limits (e.g., pagination, max results), leaving the agent uncertain about how to process the response. Given the tool's low complexity, a score of 3 is appropriate – complete enough for basic use but lacking expected details.

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, and the schema description coverage is 100% (since there are no params to document). Per the instructions, '0 params = baseline 4' but the baseline is reduced because the description does not add value beyond the schema (which is already empty). The description implies a full list without filters, which is clear, but no additional semantic richness is added. A score of 3 balances the baseline of 4 with lack of added context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states what the tool does (list itineraries) and specifies the source ('created by the Iconic Expeditions concierge') and ordering ('most recent first'). It distinguishes itself from other list/get tools by adding the scope 'concierge-created' and the sort order. A score of 5 is not given because it does not explicitly differentiate from siblings like 'list_destinations' or 'get_itinerary' by naming them.

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 provides no guidance on when to use this tool versus alternatives (e.g., get_itinerary or search tools), nor does it mention any exclusions or preconditions beyond the bearer token. With 22 sibling tools covering related operations, this is a significant omission for an AI agent to make a correct selection.

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

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

With no annotations provided, the description carries the full burden of disclosure. It reveals that the tool is public (no token needed), returns amounts in minor units, and outputs a per-person breakdown plus group total. It does not cover error behavior or rate limits, but the key operational traits (authentication, output format) are addressed.

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 four sentences with no unnecessary words. The first sentence immediately states the purpose, the second describes output, the third covers public access and units, and the fourth provides a critical usage hint. 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?

Given five parameters, no output schema, and no annotations, the description covers inputs, outputs, authentication, unit format, and the prerequisite call. It is missing details on error handling or invalid parameter behavior, but adequately equips an agent to use the tool for its primary purpose.

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 60% (3 out of 5 parameters have descriptions). The description adds value by explaining that tier_id defaults to the cheapest and nights to the reference length, and by directing the agent to get_itinerary_dossier for tier/option ids. However, it largely restates schema fields for option_ids and travellers, contributing limited new semantic information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('Price an itinerary's cost model') and specifies the resources involved: comfort tier, per-line choices, trip length, and traveller count. It differentiates from siblings by explicitly referencing the prerequisite tool get_itinerary_dossier, signaling that this tool is for pricing after obtaining dossier data.

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 provides a clear usage context by instructing the agent to 'Call get_itinerary_dossier first for the tier and option ids', establishing a sequence. However, it does not explicitly state when not to use this tool versus other pricing-related siblings (e.g., get_pricing) or give alternative use cases.

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 discloses key behavioral traits: it's a paid service, requires a bearer token, and returns a Stripe checkout URL. Since no annotations are provided, the description carries the full burden. It covers the action, requirement, and output format well, though it could mention side effects (e.g., will charges be made immediately?).

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 concise at two sentences, front-loading the key action. It wastes no words. However, it could be slightly more structured by separating the usage context from the output 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?

Given the complexity (3 parameters, a payment tool, no output schema), the description provides essential context: what the tool does, what it returns (Stripe URL), and requirements (bearer token). It lacks details on what happens after payment or error states, but given the context signals, it's fairly 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?

The schema has 3 parameters with 0% description coverage, and the description adds no extra meaning beyond listing parameter names. For example, 'notes' is not mentioned in the description, and 'contact_email' is not explained. The description does not compensate for the lack of schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Start'), the resource ('PAID booking service'), and the scope ('verification PLUS we make all the bookings'). It distinguishes itself from the sibling tool 'request_verification' by combining verification with booking, which is a specific use case.

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 provides clear context on when to use this tool: for paid bookings that include verification. It lists what bookings are made (lodges, transfers, activities, permits). However, it doesn't explicitly exclude cases where it shouldn't be used or mention alternatives for non-paid scenarios.

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 discloses that it returns a Stripe checkout URL and requires a bearer token, which are key behavioral traits. However, with no annotations provided, the description carries the full burden. It does not mention side effects (e.g., does it reserve guides or inventory?), auth failure behavior, or whether the action is reversible, leaving gaps for an agent.

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?

At 3 sentences, the description is compact and front-loaded with the primary purpose. Every sentence adds value, though a small amount of redundancy exists ('paid' in both title and first 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?

Given the complexity (paid service, deposit flow, Stripe integration) and no output schema, the description should cover return format details (e.g., is the URL in a response field?). It mentions the output but not its structure. The three parameters are partially explained. Overall adequate but not thorough.

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 0%, so the description must compensate for parameter meaning. It names 'itinerary_id' implicitly (via 'expedition'), and the mention of 'Stripe checkout URL' hints at what contact_email might be for payment receipt. However, it does not explicitly define 'notes' or 'contact_email', missing a chance to fully clarify.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Start', the specific resource 'PAID full-service, fully-guided expedition', and includes critical details like the deposit amount ($500) and the final pricing model. It is well differentiated from sibling tools like 'price_itinerary' or 'request_bookings'.

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 this is used after creating an itinerary (since it requires an itinerary_id), but does not explicitly state when to choose this over alternatives like 'price_itinerary' or 'request_bookings'. No usage constraints or prerequisites are noted beyond the bearer token requirement.

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

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

With no annotations, the description carries the full burden. It discloses that the tool is paid, returns a feasibility report and Stripe URL, and requires authentication. However, it does not explain whether the operation is synchronous or async, what happens if verification fails, or side effects like record creation. Moderately transparent but lacks depth.

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 sentences, all front-loaded: first sentence states the action and cost. Every sentence adds essential information (manual expert verification, report/price, Stripe URL, auth requirement). No redundant or vague wording. Excellent conciseness.

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 complexity (paid operation, external payment integration, no output schema or annotations), the description covers the main flow but leaves gaps: no return structure (just 'Stripe checkout URL'), no error handling, no mention of idempotency or what happens after payment. Adequate but not fully complete for a tool with no supplementary metadata.

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 67%, with notes and contact_email having clear descriptions. The description does not add extra meaning for any parameter beyond what the schema provides. For itinerary_id, which lacks a schema description, the tool description offers no additional context, relying solely on the UUID format. 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 states a specific verb ('Start'), resource ('itinerary verification'), and outcome ('feasibility report and final price', 'Stripe checkout URL'). It clearly distinguishes from siblings like price_itinerary (automated) and request_bookings (booking) by noting it is a PAID manual verification by experts.

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 for manual expert verification but does not explicitly state when to use this tool versus alternatives (e.g., price_itinerary for automated pricing, request_bookings for booking). No exclusions or prerequisites are given beyond 'Requires a bearer token.'

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It transparently reveals the multi-source search behavior, fallback mechanism to AI, and that AI results are 'clearly-labeled' with a 'source' field. However, it doesn't mention rate limits, caching freshness, or whether this is a read-only operation. The AI fallback disclosure is valuable and goes beyond basic tool purpose.

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 three sentences long, front-loaded with the core purpose and then detailing the fallback mechanism. Every sentence adds value, but the structure could be slightly tighter: the last sentence about the 'source' field could be integrated into the second sentence. Still, it is efficient and clear.

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 tool's relative complexity (multi-source search with fallback) and no output schema, the description adequately explains data freshness, source labeling, and the content types. It lacks pagination or return format details, but the 'per_page' parameter and source field provide enough context for an agent to use 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 67%: the 'type' and 'search' parameters have descriptions, while 'per_page' does not. The description adds no additional parameter details beyond the schema. With moderate coverage, the description does not compensate for the missing 'per_page' description, but the parameter is self-explanatory (a standard pagination parameter) and has clear defaults/min/max. The description adds context about the output 'source' field, which indirectly enhances understanding of 'type' results.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Search' and the resource 'Iconic Expeditions content across itineraries, activities, destinations, and posts', distinguishing it from siblings like 'get_content' (specific item retrieval) and 'search_wp_content' (WordPress-only). The specific content types are listed, making the scope 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 explains the content chain flow (WordPress -> local cache -> AI fallback) and how gaps are filled, but it does not explicitly state when to use this tool over alternatives like 'search_wp_content' or 'get_content'. The context is clear for when this tool covers multiple sources, but no exclusions or when-not-to-use guidance are provided.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only mentions the alias relationship and does not disclose any operational traits such as whether the tool is read-only, side effects, pagination behavior, or return format. For a search tool, this leaves significant ambiguity.

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 entire description is one compact sentence that conveys the alias nature and provides usage guidance. Every word is purposeful, with no fluff or redundancy. It is front-loaded and efficiently structured.

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 tool has 3 parameters, no output schema, and no annotations, the description is too sparse to be self-contained. It does not explain what the tool returns, how parameters interact, or any behavioral details. The pointer to search_content is helpful but insufficient for an agent using this tool in isolation.

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 description adds no parameter semantics at all. The input schema provides descriptions for 'type' and 'search' (67% coverage), but 'per_page' lacks a description, and the tool description does not compensate. The alias statement gives no hints about parameter meanings or usage.

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 'Alias of search_content', which clearly identifies the tool as a legacy variant but does not explicitly state what it does. The purpose is implied to be the same as search_content, but without knowing search_content's behavior, the purpose remains vague. It does distinguish itself from siblings by naming the canonical tool, but lacks a direct verb+resource statement.

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 explicitly says 'Prefer search_content' and 'kept for backwards compatibility', giving clear guidance on when to use this tool (only for legacy compatibility) and directing to the preferred alternative. This fully addresses when-to-use versus alternatives.

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 clearly explains the REPLACE semantics and the silent deletion of unspecified legs, which is crucial behavioral information beyond the schema. However, no annotations are provided, so the description carries full burden. It does not discuss required permissions, rate limits, or what happens to other blocks not sent.

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 concise with two clear sentences. It front-loads the purpose and then provides essential behavior. While it effectively earns its place, it could be slightly more structured (e.g., bullet points) for readability, but it remains very efficient.

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 high schema coverage (88%) and the complexity of the nested objects, the description is appropriately minimal. It does not need to explain return values since there is no output schema. It could mention that authentication requires a bearer token (already noted), but overall it is complete for an experienced user.

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 88% schema description coverage, the schema already describes the parameters well, so baseline is 3. The description adds value by clarifying the REPLACE semantics for legs and the optionality of blocks, which is not captured in the schema. It effectively elevates the understanding beyond the raw parameter names and types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it writes 'the planning layer above an itinerary's day-by-day' and distinguishes itself from sister tools like write_itinerary_day_detail. However, it could more explicitly differentiate from update_itinerary or create_itinerary, which also modify itineraries.

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 provides clear usage guidance: it replaces entire blocks, advises to send only intended blocks, and explicitly warns about partial leg lists deleting others. However, it does not specify when NOT to use this tool (e.g., for day-level changes vs. dossier-level changes) beyond the context of the itinerary.

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

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

With no annotations, the description must carry the full burden for behavioral disclosure. It states 'Requires a bearer token,' which is a useful authentication requirement. However, it does not describe whether updates are partial or full replacements, the side effects of changing is_public, or any rate limits. The token requirement adds value but there remains significant opacity.

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

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

Two sentences with no filler. The first sentence conveys purpose and scope; the second adds an essential prerequisite (bearer token). It could be slightly more structured (e.g., listing fields), but for a simple update tool it is appropriately concise.

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 lack of output schema and the moderate parameter count (5), the description is adequate but not thorough. It omits common return values (e.g., 'Returns the updated itinerary object'), error cases, or idempotency behavior. It also does not clarify that only the provided fields are updated. For a mutation tool, this leaves 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 only 20% (only is_public has a description). The description lists the parameter categories (title, description, dates, public status) but does not clarify formats, constraints, or relationships. For example, 'dates' ambiguously maps to start_date without confirming whether end_date is omitted or separate. The explanation adds marginal value over parameter names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (Update) and the resource (concierge itinerary) and specifies the metadata fields (title, description, dates, public status). This sufficiently distinguishes it from sibling tools like create_itinerary (which creates) and delete_itinerary (which deletes).

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 explicit guidance on when to use this tool versus alternatives like create_itinerary or partial updates via other tools. The description does not mention prerequisites (existing itinerary) or when not to use it. An agent would have to infer from the tool name.

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

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

No annotations are provided, so the description carries the burden. It discloses that the tool replaces existing narrative and callouts (a destructive behavior), but does not state return values, error conditions, or concurrency implications. It also mentions bearer token requirement, which adds some auth context. Overall, enough for a basic mutation 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?

The description is a compact two-sentence block that front-loads the core action and key constraints, with zero filler. It efficiently conveys the purpose and a few critical 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?

Given the tool's moderate complexity (4 params, no output schema, no annotations), the description covers the essential behavior (replacement, callout limit, auth) and leaves the rest to schema. It is complete enough for a straightforward write operation, though a bit more on validation or return expectations would fully round it out.

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 only 25%, but the description enumerates the main fields (narrative, callouts) and their constraints (up to three, types). It does not detail callout kinds or title syntax, which the schema partially covers via enum. The description adds some value but not full compensation for the low coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Write') and specific resource ('one day out at length') with detail on what it covers (why shaped, timing, alternatives) and up to three callouts. It also explicitly mentions replacement of existing narrative and callouts, distinguishing it from siblings like add_activity or update_itinerary.

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 implies the tool is for authoring detailed day-level content and replacing existing content, but does not explicitly say when to use it versus update_itinerary or add_day. The context is clear enough, but no explicit exclusions or alternative recommendations are given.

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