TableJourney food travel

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description goes beyond that by disclosing the result granularity (one entry per partner), what each entry contains (verified pickup facts plus a tracked booking link), and the empty-list outcome for uncovered cities. It doesn't mention pagination or partner-coverage caveats, but it adds real behavioral context.

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

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

Two compact sentences, both front-loaded with the essential scope and the failure mode. The '(read-only)' tag is redundant with the annotations, which is a minor waste, but nothing else is padding.

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

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

An output schema exists, so return-value documentation is not required, yet the description still characterizes each entry usefully. Combined with the empty-result behavior and 100% schema coverage, an agent has enough to invoke it correctly; only explicit usage guidance 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%, including the slug/name examples and the did_you_mean behavior for unknown cities, so the schema already carries parameter semantics. The description adds no extra syntax or constraint detail about country vs city usage beyond restating 'cover a city'. Baseline 3 is appropriate.

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

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

The description names the resource precisely ('car hire partners that verifiably cover a city') and the shape of the result (one entry per partner with pickup facts and a booking link). The verb is implied rather than stated, but an agent can tell instantly this is a car-hire lookup and not a stays or experiences lookup. No sibling overlaps, so explicit differentiation isn't 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?

Usage is only implied: the agent infers this is the tool for finding car hire in a given city. There is no explicit when-to-use statement, no guidance on city vs country combinations, and no routing to any alternative (e.g., when a city has no car-hire coverage, what to do instead). The 'empty list' note is behavioral rather than a usage instruction.

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

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

Annotations already declare readOnlyHint, idempotentHint, closed-world and non-destructive behavior, so safety is fully covered by structured data. The description's '(read-only)' restates the annotation, and the enumeration of returned fields overlaps the output schema, so it adds limited behavioral information beyond what is already given.

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 no filler: capability and payload first, the call-first directive last. Every clause carries information an agent needs.

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

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

The tool is simple and read-only, an output schema exists so return values need no prose explanation, and the annotations cover the safety profile. Nothing needed to invoke it correctly is missing.

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

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

There is only one optional parameter (country) and schema description coverage is 100%, with an example value supplied in the schema. The description mentions the country slug as part of the return payload but adds no filtering syntax or semantics beyond the schema, 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 ('every city the site covers') plus the payload contents (country/city slugs and hub page URL). The phrase 'the slugs the other tools accept' positions it in the toolset rather than as a search tool, so an agent can separate it from search_places or place without opening a schema.

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

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

'Call first when unsure of coverage' gives an explicit trigger condition and ordering advice versus the rest of the toolset. It stops short of naming a specific alternative for when coverage is already known, so it is clear context without full when-not guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive and openWorldHint=false, so the safety profile is covered; the description adds that results are ranked by editorial score and that venues are resolved to ids and page URLs. The parenthetical '(read-only)' is redundant with annotations but not contradictory.

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?

Usage trigger and examples come first, followed by a single sentence covering scope, read-only status, and result shape. No filler sentences.

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 a full output schema and fully documented parameters, the description only needs to convey scope, ranking, and result elements — all of which it does. An agent has everything required to call it correctly.

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

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

Schema description coverage is 100% and already documents city slugs, the limit cap, free-text query, and optional country. The description adds nothing parameter-specific, 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 resource (signature dishes of a city) plus the second half of the job (where to eat them), which cleanly separates it from peers like place, cities, and things_to_do. The concrete example queries remove any ambiguity about the output.

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

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

Gives clear triggering conditions with three quoted user phrasings covering both 'what to eat' and 'where to find a specific dish'. It stops short of naming alternatives or exclusions (e.g. when to prefer place or search_places instead), so it is strong but not a full routing rule.

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 read-only, idempotent, non-destructive behavior, and the description reinforces that while adding useful context about result contents and ranking. The note that results are ranked by relevance to query, otherwise popularity, adds behavioral information beyond the schema and 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 front-loaded with use cases, then quickly covers what is returned, safety, and ranking. It is compact and every sentence contributes useful selection or interpretation guidance.

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

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

Given five parameters, full schema coverage, an output schema, and rich annotations, the description provides enough context to select and invoke the tool correctly. It covers the food-focused scope, example queries, result fields, ranking behavior, and read-only nature.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by explaining that results are ranked by relevance to query when supplied and by popularity otherwise. It does not add much beyond the schema for city, country, limit, or food_only, but the query ranking semantics are helpful.

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

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

The description gives a clear verb and resource: finding bookable food tours, cooking classes, tastings, and market tours in a city, with concrete examples. It scopes the tool well, but it does not explicitly distinguish it from broad siblings like things_to_do or tickets, so it falls short of a 5.

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

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

It opens with explicit use cases such as 'a street food tour in Bangkok' and 'pasta-making class in Rome,' which clearly tells an agent when to use this tool. It does not state when not to use it or name alternatives, so it is strong but not complete.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and the description's '(read-only)' is consistent rather than contradicting. It adds genuinely useful behavior beyond the annotations: results are resolved to the next edition with starts_on/ends_on, plus an organiser source URL and a page to cite, which tells the agent the data is citation-ready and date-resolved.

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

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

Front-loads the usage trigger, then the capability, then the return shape — a sensible ordering with no filler prose. Minor redundancy: '(read-only)' and the date-window phrasing echo annotations and schema, and the quoted example list is long, but each element is functional.

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

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

For a six-parameter, zero-required search tool with an output schema and full annotation coverage, the description supplies everything the agent needs: when to call it, what dimensions it filters on, and that dates are pre-resolved to the next edition. Return-value detail is extra rather than required, since the output schema exists.

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

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

Schema description coverage is 100%, so every parameter including city, country, date_from/date_to semantics, and the limit/API-key cap is already documented in the schema. The description only paraphrases the filter set ('city, country, a date window and text') without adding format or interaction details such as country being optional where city is given. 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 resource (food festivals / Christmas markets) with clear capability: 'Food festivals with their next resolved dates' and 'Filter by city, country, a date window and text.' The domain is clearly distinct from siblings like things_to_do, experiences, and tickets, so an agent can route without opening the schema.

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

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

Opens with an explicit trigger ('Use when the user asks what food festivals, food events or Christmas markets are on') and supplies four realistic user phrasings that map directly to invocation contexts. There is no explicit when-not guidance or naming of an alternative tool to use instead, which keeps it from a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds useful behavior beyond that: what each venue is resolved to (id, address, hours, page URL) and the empty-list case when no itinerary exists for a city.

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

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

Two tight sentences: the usage trigger is front-loaded, then output shape and the empty-result edge case. No 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?

With an output schema present, return values need not be explained, and annotations carry the safety profile. The description covers purpose, triggers and the empty-result behavior; it could still say whether results are ranked/capped or how many days are supported, but nothing essential to correct invocation 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% and both parameters are documented there (slug-or-name forms, did_you_mean behavior). The description adds only the implicit 'city' scoping, 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+resource ('Editorial day-by-day food itineraries for a city') and distinguishes itself from siblings like things_to_do, plan_day and dishes by naming the content type. The parenthetical example queries make 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?

Gives explicit trigger phrasing ('a two-day food itinerary for <city>', 'how to spend 48 hours eating in <city>') so an agent can route on natural user intent. It does not name the closest alternative (e.g. plan_day) or state exclusions, so routing against siblings still requires inference.

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

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

Annotations only declare that this is a non-read-only, non-destructive, non-idempotent, open-world call. The description goes well beyond that by disclosing the two-step verification flow, that a code is dispatched to the address, that the API key is unchanged, and the account-recovery/payout stakes. It does not cover failure cases or re-request behavior for a non-idempotent 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?

Three compact sentences with no filler, and the crucial follow-up tool is named early. The auth requirement is front-loaded at the expense of the operation statement, which is a minor ordering weakness rather than a verbosity problem.

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

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

For a one-parameter tool with no output schema, the description supplies the surrounding workflow, the downstream confirmation call, and the business reason the step exists. Only error handling and re-send/rate behavior remain unstated.

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

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

Schema coverage is 100% and the schema already explains the single email parameter, including the 'inbox you or your operator can read' constraint. The description's mention that a code is sent to the address is behavioral context rather than added parameter meaning, so the 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 makes clear this attaches an email to a partner account created without one, and that a verification code follows. The resource and operation are identifiable, though the sentence structure leads with the auth requirement rather than the verb, so it is slightly less crisp than a direct 'adds X to Y' 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?

It names the triggering condition ('an account that joined without an email') and the mandatory follow-up step with a named sibling ('confirm it with partner_confirm'), plus the prerequisite for payouts. It stops short of an explicit exclusion (e.g., what to do if an email already exists), so it falls just below a full routing instruction.

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

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

Annotations only set the safety profile (readOnly=false, destructive=false, idempotent=false); the description adds the operationally critical fact that the API key is shown once and cannot be re-read, plus exactly how to present it (Authorization: Bearer or X-API-Key). That is real behavioral context an agent cannot get from the schema or annotations.

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

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

Front-loads the action in a short first sentence, then uses the second sentence for return values. The parentheticals are dense but each clause (one-time key display, auth header syntax, ?ref usage) carries information the agent needs.

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 correctly covers what confirmation returns (API key, referral code) and how to use each. It omits failure behavior for an invalid/expired code and does not note that the call is non-idempotent, leaving minor gaps for a state-changing 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 includes a format example for the code (ABCD-2345) and the meaning of email, so the baseline is 3. The description only adds the provenance of the code (from partner_join), which is a thin addition 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?

States a specific verb+resource (confirm the email address for the partner account) and explicitly ties the required code to its origin tool, partner_join. This distinguishes it cleanly from lookalike siblings such as partner_signin, partner_signin_code and partner_join without opening any schema.

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

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

Gives the clear prerequisite that the code comes from partner_join, which establishes the workflow order (join -> confirm). It does not name or exclude alternative auth paths (partner_signin, partner_signin_code), so it stops short of full when/when-not guidance.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds useful auth context by stating that an API key or OAuth token is needed and that the code comes from a payout email, but it does not explain what mutation occurs or whether the confirmation is final.

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 short with no filler, but it front-loads authentication prerequisites rather than the tool's action. It is concise yet lacks the sentence that would make the purpose clear and actionable.

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 tool with annotations covering its safety profile, the description still omits what the tool does and when to use it. An agent cannot choose between this and sibling tools such as partner_confirm from the description alone.

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

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

Schema description coverage is 100%, and the schema already describes 'code' as 'The emailed code.' The description's 'The code from the payout email' adds marginal source context but no new syntax or format detail. Baseline 3 applies when the schema already documents 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 only states prerequisites ('Needs your API key or OAuth token') and the code source; it never says what the tool does, such as confirming payout details. It does not distinguish this tool from sibling tools like partner_confirm or partner_payout_method.

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

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

There is no guidance on when to use this tool versus alternatives such as partner_confirm, partner_payout_method, or partner_link. The only usage-like information is an authentication prerequisite, not a selection condition.

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 a non-read-only, open-world, non-destructive write, and the description adds real context: the account is free, email is optional with different downstream consequences, and terms acceptance is mandatory. It does not mention that repeat calls are non-idempotent (each call would likely create a new account), which is the one behavioral trait left implicit.

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

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

Front-loaded with the purpose, then the branching behavior and prerequisites; nearly every sentence earns its place. The 'No inbox?' sentence with its nested parenthetical is slightly dense but still readable.

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 does the needed work by telling the agent what the response contains (API key and referral code) in the no-email path and that the email path defers to partner_confirm. What partner_confirm ultimately returns is left unstated, a minor gap for a multi-step flow.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it clarifies that omitting email is a supported path with its own return payload, and that the agent's operator is the member and payee (relevant to the 'kind' choice). That is genuine added semantics rather than restatement.

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

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

States a specific verb and resource ('Create a free partner account') plus the business outcome (commission share). This clearly separates it from siblings like partner_add_email, partner_confirm, partner_signin, and partner_stats.

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 routes the two flows: with an email, a one-time code goes to partner_confirm; without an email, the response carries the API key and referral code directly. It also names partner_add_email as the prerequisite for payouts and states accept_terms must be true — when-to-use and alternatives are fully covered.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the useful auth context ('Needs your API key or OAuth token') and the transformation it performs, but says nothing about rate limits, return shape, or what happens with an invalid ref.

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 no filler, and the auth requirement is front-loaded. The fragmentary phrasing costs a little readability but nothing 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?

For a one-parameter, read-only, idempotent tool with no output schema, the description plus title adequately explain input and result (a URL with the ?ref= code appended). Missing only edge-case behavior, which is minor at this complexity.

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

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

Schema description coverage is 100% for the single 'url' parameter, so baseline is 3. The description slightly enriches it by noting that 'any page of the site' is acceptable input, but adds no format or default details beyond what the schema provides.

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

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

The definition conveys that it produces a tablejourney.com page link with your ?ref= referral code added, which is a recognizable resource and effect. However, it never states an explicit verb (e.g., 'generate' or 'build') and reads as a fragment, so the agent must infer the operation. It does distinguish itself from the partner_join/signin/stats siblings by the ?ref= mechanism.

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

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

There is no when-to-use or when-not-to-use guidance and no named alternative among the many partner_* siblings. The sentence about the API key/OAuth token is a prerequisite, not usage context for choosing this tool.

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 non-read-only, open-world, non-idempotent behavior, so the bar is lower. The description still adds real context beyond them: authentication via API key or OAuth token, an emailed verification code, and the fact that changes are provisional until partner_confirm_payout. It does not say whether an existing payout method is overwritten, which is the main remaining behavioral 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 text is front-loaded with the authentication requirement and then condenses ten parameters into groupings without repeating the schema verbatim. It is dense, using semicolons and parentheticals, but nearly every clause carries information an agent needs. Slightly more separation between the method enumeration and the confirmation step would improve readability.

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

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

For a 10-parameter mutation with 10% schema coverage and no output schema, the description is respectably complete: it covers auth, the type-to-field mapping, and the deferred-effect flow. It still omits what happens to an existing payout method, error/validation behavior, and whether the email code is passed to this tool or to partner_confirm_payout.

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 10% (only 'type' is documented), so the description must compensate, and it largely does: it maps paypal to paypal_email, the crypto types to address with network-specific meanings for usdc_base/usdc_solana/eth/sol/btc, and bank to holder, country, currency, iban or account_number, and bic or routing_number. This resolves the conditional-field puzzle the schema leaves open. Formats (IBAN/address syntax) are still unexplained, preventing a 5.

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

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

The description plus title make clear this tool registers a payout destination, and it enumerates the three method families (paypal, crypto, bank) with their required fields. It also distinguishes itself from the sibling partner_confirm_payout by stating that the details only take effect after that call. It stops short of a single explicit 'sets the partner's payout method' verb sentence, which keeps it off 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?

Usage is implied by the payout-method framing and the sequencing note about partner_confirm_payout, so an agent can infer the two-step flow. However, it never states when to call this versus partner_confirm_payout, nor any prerequisites such as whether an existing method is replaced or whether the account must already be a partner. There are no explicit exclusions or 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?

Annotations establish non-read-only, non-idempotent, non-destructive behavior, and the description adds the key side effect the annotations don't convey: the previous API key stops working. It still does not explain the returned value's format or expiry.

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?

A single front-loaded sentence whose parenthetical carries the one non-obvious consequence. No 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 2-parameter auth tool with no output schema, the description covers the action, inputs, and credential-invalidation effect adequately. Only the return value's nature (format/expiry of the new key) is left implicit.

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

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

Schema description coverage is 100% with both parameters documented, so the baseline is 3. The description adds no syntax, format, or constraint detail beyond what the schema already supplies.

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 (exchange) and resource (emailed sign-in code) and names the outcome (new API key). It is clearly distinguishable from credential-issuing siblings like partner_signin_code or partner_join.

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 'emailed sign-in code' implies this is the second step of a process begun by partner_signin_code, but it never explicitly says so or gives prerequisites. Usage is inferable 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?

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the agent knows this is a non-idempotent side-effecting action. The description adds that an email is actually dispatched and that the code is one-time, which is genuinely useful context beyond the annotations, but it omits rate limiting, code expiry, and whether requesting a second code invalidates the first.

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?

A single sentence with the action and resource front-loaded and zero filler. The parenthetical efficiently carries the workflow linkage without a second sentence.

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

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

For a one-parameter tool with no output schema this is close to sufficient, and the annotations cover the safety profile. Still missing for correct invocation: what happens after the code is emailed, code validity/expiry, and error behaviour for an unrecognized email address.

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 and schema description coverage is 100% ('Your partner email.'), so the schema already carries the full parameter burden. The description adds no syntax, format or constraint information beyond what the schema 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?

States a specific verb and resource — email a one-time sign-in code to a partner account — and names the sibling tool partner_signin in the parenthetical, so the agent can distinguish this code-delivery step from the sign-in step itself. It is clear but the differentiation is embedded in a parenthetical rather than stated as a routing rule.

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 parenthetical 'for a new API key with partner_signin' implies the workflow context (call this to obtain the code that partner_signin consumes), which is useful implied usage. However, there is no explicit when-to-use vs. when-not statement, no prerequisite (existing partner account) and no note on what to do if a code was already requested.

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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description earns credit for the auth requirement and for explaining the earnings lifecycle (pending until the partner pays, then payable after the hold). It stops short of return shape or pagination/rate-limit detail, so it isn't a 5.

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

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

Two sentences with no filler, and the auth prerequisite is front-loaded. It is dense but every clause adds information; only the earnings-status parenthetical could be tightened.

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 does convey what comes back and the meaning of the earnings statuses. It is incomplete on the one thing the agent must supply, the `days` window, leaving a meaningful gap.

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

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

There is one parameter, `days`, and schema description coverage is 0% — neither the schema nor the description explains it. The description never mentions the time window at all, so it fails to compensate for the coverage gap (default 30, max 365 is left for the agent to infer).

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 resource and enumerates what it returns: visits, partner clicks, and earnings broken out by status. An agent knows this is a read-only reporting tool. It does not distinguish itself from sibling payout/confirm tools (partner_confirm_payout, partner_payout_method), so it falls short of a 5.

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

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

The only directive is an auth prerequisite ('Needs your API key or OAuth token'), which is a condition rather than when-to-use guidance. Nothing tells the agent when to reach for partner_stats versus partner_confirm_payout or partner_payout_method, and no exclusions or alternative routes are named.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: the error contract ({error: ...} for malformed or unknown ids) and the breadth of returned fields including open_now_utc and three nearby venues.

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

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

Front-loaded with the core action and resource, then a compact inventory of return contents and the error case. Every clause carries information; only the long field list pushes against the density limit.

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 the return-value burden and does so partially, naming the key fields, nearby venues, and the error shape. It is complete enough to call correctly, though pagination or response envelope details are absent.

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

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

Schema coverage is 100% and the schema itself documents the id format with a concrete example ('italy/rome/restaurants/roscioli'), so the baseline is 3. The description only adds the failure mode for an invalid id, not additional syntax or format 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?

States a specific action and resource: 'One venue in full by id', which plainly separates it from the plural search_places sibling. It also enumerates what 'in full' means (provenance, hours, booking link, nearby venues), so an agent knows exactly what comes back.

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

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

Usage is implied rather than stated: the id is described as the one 'search_places returned', which signals this is the detail-lookup follow-up to a search, and the malformed/unknown-id error case is disclosed. However, it never explicitly says when to use this instead of search_places or any other sibling.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces 'read-only' while adding substantial context the annotations cannot: every stop is checked open at its slot time on the given date, filtering is by neighbourhood/dietary/price tier, and the result includes a bookable experience plus itinerary titles.

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

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

Front-loaded with the activation condition and examples, then the output contract and the sibling handoff. Dense but every clause carries a distinct fact; there is no filler or repetition.

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 the return contract and does so fully: per-slot venues, date-validity checking, one bookable experience, and the list of editorial itinerary titles. Nothing an agent needs to call or interpret this tool 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 baseline is 3. The description restates the filter concepts (neighbourhood, dietary need, price tier) but adds no syntax, format, or defaulting detail beyond what the schema fields already document.

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 ('Compose a food day for one city') and spells out the output shape: one best-scored open venue per slot from morning to evening, plus one bookable experience. It also distinguishes itself from the sibling `itineraries`, which an agent can route to without opening either schema.

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

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

Opens with an explicit trigger ('Use when the user wants a day planned') followed by two concrete user utterances. It goes further and names the alternative: editorial itineraries are 'the better plan when one exists', with the exact sibling to fetch them (`itineraries`).

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

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

Beyond the annotations, the description discloses ranking behavior (relevance then editorial score), provenance fields (source URL, checked_on, open_status), a citable page URL and tracked booking link, and the unknown-city response shape. It also notes that venues with unparseable hours are returned last and flagged, which is useful behavioral context not present in 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 dense but front-loaded: it opens with the triggering user scenario, then lists filters, ranking behavior, and return-shape caveats in a compact paragraph. Every sentence contributes actionable information without 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?

With an output schema present, rich annotations, and 100% schema coverage, the description still covers the essential usage trigger, filterable dimensions, ranking, provenance, and the did_you_mean edge case. An agent has enough context to select and invoke the 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?

Schema description coverage is 100%, so the schema already documents all twelve parameters thoroughly, including examples and defaults. The description restates the filterable dimensions but adds little syntax or semantic detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource ('Search verified venues') and supports it with concrete user-query examples like 'best ramen in Tokyo' and 'a wine bar near me in Paris'. It clearly conveys a search operation, though it does not explicitly distinguish itself from the sibling `place` detail tool.

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

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

It gives explicit when-to-use guidance via 'Use when the user asks where to eat or drink in a city' and lists representative utterances. It does not name a sibling alternative or state when not to use this tool, so it stops short of full routing guidance.

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

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

Annotations already cover readOnly, idempotent and destructive flags, so the description only needs to add behavior beyond that — and it does, disclosing that prices are not returned and that the partner page carries them, plus that each listing has a tracked booking link. It says nothing about result caps or empty/did_you_mean handling beyond what the schema notes.

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 user-facing intent and then the payload contents. Every clause earns its place, with no repetition of the title or 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?

With no output schema and no annotations on return shape, the description correctly compensates by describing what comes back (hotel listings with tracked links, partner search links) and what does not (prices). Missing only minor details such as result-count behavior when limit truncates the 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 parameters (city, country, limit with default 10 and range 1-50) are fully documented in the schema already. The description adds no format or syntax detail for those arguments beyond the schema, so the baseline 3 applies.

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

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

The description names a specific resource (hotel listings plus partner search links for a city) and states what is returned, so the agent knows this is the lodging tool rather than things_to_do or experiences. It never names a sibling tool to contrast against, which keeps it short of the top band.

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

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

It gives two explicit trigger phrasings, 'where to stay in <city>' and 'hotels in <city>', which is actionable routing context. It stops short of stating when NOT to use it or pointing at an alternative sibling when a query is only tangentially lodging-related.

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/idempotent/destructive=false, so the safety profile is covered. The description adds genuine operational context beyond that: a single call aggregates many categories, each result carries its own page and a tracked booking link, and the agent must pass affiliate links through unchanged — a non-obvious obligation worth disclosing.

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

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

Front-loads the trigger ('Use when the user is planning a trip...') before the payload description, which is the right order. It is somewhat dense in the middle enumeration and the parenthetical '(read-only)' duplicates the annotation, but every sentence carries routing or behavioral value.

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 usefully enumerates what comes back and in what shape (each item has a page plus booking link), and the schema covers all inputs. Mild gaps remain about result count, pagination or how festivals are date-filtered.

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%, with city/country slugs, did_you_mean behavior and ISO date fields all documented in the schema. The description adds no parameter-level detail beyond the schema, 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+resource (returns things to do in a city) and enumerates the concrete payload: food tours, classes, tastings, attraction tickets, festivals, places to eat, stays, car hire. The 'START HERE for "what can I do in <city>?"' framing distinguishes it from narrow siblings like experiences, festivals, tickets and stays.

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

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

Gives explicit trigger conditions with two realistic user utterances and marks itself as the entry point for city-activity questions, which routes the agent correctly. It stops short of naming when NOT to use it or which sibling to fall back to (e.g., car_hire alone, plan_day, itineraries).

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the '(read-only)' tag is largely redundant. What the description does add is beyond the structured data: the deduplicated per-partner granularity with a tracked booking link, and the explicit empty-list outcome when no partner covers the city. Return-format detail is lighter than it could be, but an output schema exists.

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

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

Two sentences, front-loaded with the resource and scope, with the sibling relationship and the empty-result behaviour packed in without filler. Every clause carries information.

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

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

With rich annotations, full schema coverage and an output schema, the description needs only to establish scope and routing, which it does. It could have stated the explicit this-vs-experiences rule, but nothing an agent needs to invoke the tool correctly is missing.

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

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

Schema description coverage is 100% — the schema already documents both city and country with slug/name formats and the did_you_mean fallback. The description adds nothing about parameter syntax or the optionality of country, 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 resource (attraction tickets, city passes, tour partners) with a scope qualifier ('verifiably cover a city') and the return granularity ('one entry per partner with a tracked booking link'). It also names the sibling `experiences` as the adjacent tool, so an agent can distinguish them without opening either schema.

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

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

Saying it 'Complements `experiences`' implies the division of labour but never states when to pick this over that sibling, nor any exclusion. 'Empty list when none covers the city' describes an outcome, not a usage rule. Usage is inferable but not spelled out.

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