entityindex.ai

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 fully covered and the description only needs to add context. It adds one valuable behavioral fact — that the response shape is identical to the vertical-specific get tools — but says nothing about miss/not-found behavior or what the returned record page URL and note fields look like.

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?

Very tight — two clauses plus an inline JSON example, with the generic-lookup purpose front-loaded. The fragmentary colon-and-parenthetical style is efficient, though the example could have been annotated to show which fields are required versus illustrative.

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 4-parameter read tool with full annotations and no output schema, the core call path (vertical + slug, obtained from search_entities) is adequately conveyed. But the country parameter is undocumented and no failure mode is described, so an agent would not know how to use or omit country 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 only 25% (only lang is documented in the schema), so the description must compensate, and it partially does: it explains the vertical+slug composite key and provides a concrete example object showing the expected format. It leaves slug format unexplained beyond provenance, and the country parameter (enum: andorra) is completely unaddressed in both schema and description, which is the notable 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?

"Generic record lookup: vertical + slug" names a specific verb and resource and states the composite key it uses. It also explicitly positions itself against the vertical-specific siblings ("Same output as the vertical-specific get tool (e.g. get_hotel)"), so an agent can distinguish get_entity from get_hotel/get_restaurant 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?

The parenthetical "(from search_entities)" implies the expected workflow of searching first to obtain a slug, which is genuinely useful context. However, it never says when to prefer this generic tool over get_hotel or get_restaurant, nor what happens if the vertical/slug pair doesn't exist; the choice between generic and vertical-specific is left to 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 already declare readOnly, idempotent, closed-world, non-destructive behavior, so the safety profile is covered. The description goes beyond that by enumerating the payload shape (verified facts with source URL and check date, notes, contact, booking engine, record page, JSON API URL) and explicitly flagging the negative space ('No prices or photos') and the booking_link redirect with src=entityindex.

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 usage trigger before the return payload, and the sentence about returned data is dense but informative rather than padded. The single long enumeration of return fields is slightly heavy but every item carries selection 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 takes on the return-value burden and handles it well, listing the record contents and explicitly excluding prices and photos. It omits error behavior for an invalid slug and any auth or rate-limit context, which are minor for a read-only lookup 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%, so the baseline is 3. The description restates the slug's origin ('slug from search_hotels') and repeats the example already present in the schema, and says nothing about the lang parameter, so it adds little meaning beyond structured fields.

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 ('Get the full verified record of one hotel') and scopes it to a single property, which cleanly separates it from the plural search_hotels list tool it references. It does not address the sibling get_entity, so an agent cannot fully rule out overlap with the generic entity getter from this text alone.

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 sequencing ('Use after search_hotels') and the triggering intent ('when the user wants details or a booking link for one property'), plus identifies where the required slug comes from. No exclusions or failure conditions are stated (e.g. what to do if the slug is unknown), 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 already declare readOnlyHint=true and openWorldHint=false, so safety is covered. With no output schema, the field list (address, geo, cuisine, hours, reservation channel, diet, slope access, level, sources with dates and licence) is a genuinely valuable disclosure of what a call yields, but nothing is said about behavior when a slug does not match.

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

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

Two short sentences, front-loaded with the usage trigger and then the input, with the return payload listed at the end. The return-field list is dense and slightly run-on but every item conveys real 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?

For a single-parameter lookup tool with no output schema, the description covers the trigger, the input format, and the returned fields, which is close to sufficient. Missing only failure/empty-result behavior, which is minor for a read-only lookup.

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 carry the parameter meaning; it does name the parameter and give two concrete slug examples, which clarify the identifier format. It does not state that the slug comes from search_restaurants results, leaving that link implicit.

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

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

The description names a specific verb (get) and resource (one restaurant record) and makes the singular-record scope explicit, which separates it from search_restaurants. It does not explicitly distinguish itself from get_hotel or get_entity, though the resource names make the difference inferable.

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 after search_restaurants' gives a clear ordered workflow: find candidates with the search tool, then fetch full detail here. There is no explicit when-not guidance or mention of what to do when a slug is unknown, so it stops short of the top band.

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 and non-destructive, so safety is covered. The description adds genuinely useful behavior beyond that: results carry counts, and only areas that actually have accommodation in the index are returned (an implicit coverage limit). A minor gap is that it doesn't say whether the area names are the exact values search_hotels expects as filter keys.

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, front-loaded with 'Use to', that carries purpose, sequencing and an example user question with 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 zero-param, read-only lookup with annotations covering the safety profile and no output schema needed, the description supplies everything required to select and call it correctly, including the ordering relationship with search_hotels.

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, so per the baseline this scores 4. There is nothing for the description to disambiguate beyond what the empty schema already communicates.

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 ('discover') plus concrete resource ('which parishes and localities have accommodation in the index') with the geographic scope named. It also differentiates itself from search_hotels, which is the sibling an agent would otherwise confuse it with.

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?

States exactly when to reach for it: before filtering search_hotels by area, or to answer a 'where can I stay' question. The alternative (search_hotels) and the condition that selects it are both named, so no inference is required.

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/non-open-world, so the safety bar is covered. The description adds useful behavior beyond that: the URL pattern /{country}/{vertical}/{slug}/, the enumerated response languages, and that record counts are returned.

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?

One front-loaded sentence carries the core payload, with a short illustrative tail sentence. Efficient, though the parenthetical language list and the trailing example add slight bulk.

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

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

For a zero-parameter, no-output-schema catalog tool, the description fully covers the return shape (verticals, countries, languages, filters, URL pattern, record counts). Nothing needed to call 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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies no filtering is needed to call it, and mentions the filters exposed on the listed resources rather than inventing inputs.

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 (Lists) and resources (verticals, countries, response languages), and immediately distinguishes itself from siblings like search_entities/get_hotel by being a discovery/catalog endpoint. An agent can tell what this returns 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?

The example ('Today: hotels in Andorra') implies this is the entry point for discovering what data exists, but there is no explicit when-to-use vs alternatives guidance or any exclusion rules. Usage is inferred 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered. The description adds useful context that filters are 'vertical-specific verified booleans' and lists which ones exist for hotels, but says nothing about result volume, pagination, or what a record contains.

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?

Dense but front-loaded: purpose first, then valid verticals, then parameters, then an example. The enumerated filter keys are long but earn their place given the schema gap; 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 7 parameters, a nested open-ended filters object and no output schema, the description covers purpose, verticals and filter keys but omits the lang parameter, the limit default/range, and any sense of result shape or paging. Adequate to make a correct call, not complete for the tool's actual 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 coverage is low at 29% (only lang is documented inline, and filters only says 'see list_verticals'), and the description fills much of that gap: it names vertical as required, enumerates country, area, query, filters and limit, spells out hotel filter keys (spa, pool, parking, pets, ski_in_out, family, min_stars, type), and gives a usage example. The main miss is that 'lang' goes unmentioned in the 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?

States a specific verb and resource ('search across entityindex.ai verticals') and explicitly positions itself against the vertical-specific siblings by saying it serves 'same data as the vertical-specific tools.' An agent can tell it is the generic entry point versus search_hotels/search_restaurants, though it never states outright which to prefer.

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 roster of verticals ('hotels' and 'restaurants', country 'andorra') and routes to list_verticals for discovery, plus a concrete worked example. It never says when to pick this over search_hotels or search_restaurants, so the choice between generic and specific is left to 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 already cover the safety profile (readOnly, idempotent, closed-world), so the bar is lower, yet the description still adds substantial behavior: tri-state filter semantics, the rule that unknown values are excluded when a filter is set, the contents of each result (verified_facts with source URL and date, record page, booking_link), and a licensing/citation obligation. This is well beyond what the annotations convey.

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 trigger and coverage before filters, output and examples, and nearly every sentence earns its place. The single dense paragraph is long for a 12-parameter tool and repeats the Grandvalira village list that the area parameter already implies, so it would benefit from light structuring.

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

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

There is no output schema, but the description still describes the return payload (verified_facts, record page, booking_link) and the absence of prices/photos/availability. Combined with coverage limits, filter semantics and the citation requirement, an agent has everything needed to call and interpret 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?

Schema coverage is 75%, and the description compensates for the remainder with meaning the schema cannot carry: 'true = the official website explicitly says so; false = it explicitly says no; properties with unknown values are excluded', plus definitions for min_stars ('category stated on the official site') and the Grandvalira alias expanding to five villages. This is real semantic value, not 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 (search) and resource (hotels in Andorra) with a precisely bounded scope: three named parishes plus Grandvalira. An agent can immediately tell this is the hotel-specific search rather than the generic search_entities. It stops short of 5 because it never names the sibling tools it should be preferred over.

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 when-to-use trigger ('Use this when a user asks for accommodation in Andorra') backed by five concrete example queries, and closes with explicit when-not guidance ('No prices, photos or availability'). The agent knows both the entry condition and the limits of the tool before calling 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?

Goes well beyond readOnlyHint/openWorldHint: discloses data provenance (OSM, ODbL, official sites), the three record levels and that 'cliente' is sponsored-but-flagged, the ranking rule (relevance, completeness, name — never paid), and that unknown values are excluded unless include_unknown=true. It also sets expectations on absent data (no prices or ratings) and requires citing 'entityindex.ai', which is exactly the kind of contract an agent needs before answering.

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 phrase, then compresses examples, provenance, level taxonomy, ordering, unknown-handling and caveats into one tight block with no filler sentences. Every clause carries operational 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?

For a read-only, no-output-schema search tool with 22 optional filters, the definition covers the essentials an agent needs to call it responsibly: what corpus it searches, how results are ordered, how nulls are treated, and what the answer must not claim (prices/ratings). Remaining gaps such as pagination shape or the exact free-text matching of 'query' are minor.

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 only 23% schema coverage across 22 parameters, the description carries real weight here: it defines the opaque 'level' enum values (basica/verificada/cliente) and the cross-cutting semantics of include_unknown, which the schema does not explain. It leaves several filters (price_range, query, season, kids/groups, ski_access) to the agent's intuition, so compensation is good but incomplete.

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?

Starts with a specific verb and scope ('Use this when a user asks where to eat in Andorra') and backs it with six concrete query examples that map directly to filters (open now, cuisine, ski area, diet, reservations). The framing 'Index of all restaurants in Andorra' plus the sibling names (get_restaurant, search_hotels, search_entities) makes it obvious this is the filtered-list tool rather than a single-record fetch.

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 triggers via varied example phrasings, which is strong guidance for an LLM router. It does not state when NOT to use it or name siblings explicitly (e.g. get_restaurant for a known restaurant, search_entities for cross-vertical queries), leaving that inference to the agent.

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