TripHook

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description adds meaningful behavior beyond that: the reply ends with links that should be rendered as one short line, and the privacy constraint "Public fields only, never a person."

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 correctly with the use case, but the rest is a single dense run-on sentence that bundles return fields, presentation rules, and privacy notes. The link-rendering instruction in particular bloats an otherwise functional 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?

With no output schema, the description usefully enumerates the return shape (event ticket link, whats_on page, company count and links) and the privacy constraint. Enough for an agent to call it correctly; only pagination/limits are unmentioned.

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 0%, so the description must carry the parameters. It labels both explicitly ("city slug", "date YYYY-MM-DD"), matching the schema patterns and giving an agent the expected formats without opening 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?

Specific verb+resource: events happening in a city on a given date plus whether other travellers are attending. The scope is unambiguous and clearly distinct from list_cities/search_destinations, though the siblings are never named outright.

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

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

"Use for any question about what is happening in a city on a date... and whether other travellers are going" gives a clear use condition. It stops short of naming alternatives or stating when-not to use it versus search_public_hooks.

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, closed-world behavior, so the safety profile is covered. The description adds genuine extra context: the reply ends with links and they should be rendered as one short line. It stops short of auth/rate/edge-case detail, but for a no-arg read tool that is a minor 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?

Purpose and returned data are front-loaded before the routing caveat, and the link-rendering tip is a single compact sentence. The middle clause ('with counts of trips and day outs... each city's slug... and its TripHook city page (url)') is slightly run-on, costing a little 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?

With no output schema and no parameters, the description carries the full burden and does so: it explains the returned fields, the trailing links, how to present them, and when to prefer a sibling. An agent has everything needed to call and interpret it.

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

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

The tool takes zero parameters and schema coverage is 100%, so the baseline is 4. The description correctly does not invent parameters; it instead explains the fields returned (slug, URL), which compensates for the absent output schema.

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

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

States a specific verb and resource (list cities) and immediately qualifies scope: cities with open group trips and day outs. It also enumerates the returned fields (trip/day-out counts, slug, city page URL), which tells an agent exactly what this tool yields.

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 agent: use this to find cities with open hooks, but for 'where should I go', 'where is warm', or budget questions use search_destinations instead. This gives both the when and the when-not with a named alternative.

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 readOnlyHint, openWorldHint, idempotentHint and destructiveHint all provided, the safety profile is already covered. The description adds genuinely useful context: ranking originates from Vienna or the departure city, each result carries a why-it-matched reason, a Forecast vs Typical weather label, a price explicitly disclaimed as an estimate, and no personal data is involved.

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 use case and packs real constraints into a dense paragraph. However, several sentences are presentation directives ('Show the weather as "forecast" or "typical"', 'do not repeat the weather source name') that dilute the operational content.

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, nested-object tool with no output schema, the description does the heavy lifting on result shape (city, country, why, weather label, estimate price, url, crew_url) and ranking behavior. It is close to complete; only sibling routing is thin.

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 every parameter, including defaults, enums, ranges and patterns. The description largely restates this (dates or month, limit max 20, optional list), adding little beyond what the schema carries; 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 precise verb+resource (destination search) and frames it as the TripHook Discover signed-out search, ranked from Vienna or a departure city. This distinguishes it from list_cities and search_public_hooks, so an agent can pick it without opening a schema.

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

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

Gives explicit trigger language ('any question like "where should I go" with a budget, a temperature, a mood, dates or a month') and states the dates-or-month requirement. It stops short of naming alternatives or when to prefer a sibling such as list_cities, so it is strong context without full routing.

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

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

Annotations already cover readOnly, idempotent, non-destructive and closed-world behavior. The description adds real context beyond them: what each hook carries (its public page url and, for a day out, the event_page), that the reply ends with links to render as one short line, and the privacy constraint 'Public fields only, never a person'. It does not cover pagination, but for a read-only search the safety profile is already handled.

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

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

Front-loads the core purpose and filter list, then couples the return-format instruction and the sibling routing rule. It is dense rather than bloated, though the rendering instruction for the trailing links is a touch detailed for a tool 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?

With no output schema, the description carries the return-value burden and does so by describing the url / event_page fields and the trailing link line. Combined with sibling routing and the privacy note, an agent has what it needs to call this correctly; only the unexplained limit parameter is missing.

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

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

Schema coverage is 50%, so the description must compensate and largely does: it names city slug, month (YYYY-MM), kind (trip or dayout), budget tier and mood as the queryable dimensions, matching five of six parameters and the enum semantics. The limit parameter is neither described here nor in the schema, leaving that one gap.

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 (search public TripHook hooks) and names the exact scope: open trips or day outs to join, filterable by city, month, kind, budget or mood. It explicitly distinguishes itself from sibling search_destinations, so the agent can pick correctly 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?

Gives explicit when-to-use (any question about open trips or day outs to join) and when-not-to-use with the alternative named: 'For any where should I go, where is warm or budget question, use search_destinations instead.' Both routing conditions are concrete.

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