discava – Business Directory for AI

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 safe read profile is covered. The description adds the field list and batch behavior, but does not disclose additional behavioral details such as output shape, pagination, or rate limits. This is acceptable given annotation coverage, but not exceptional.

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

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

Two sentences with no filler: the first states the purpose and enumerates returned fields, the second covers the batch format. Both sentences earn their place and the most important action is front-loaded.

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-only tool, the description covers what resource is fetched, what fields are included, and how to batch requests. The absence of an output schema is partially mitigated by the field list. It does not state the exact response container for batch requests, but this is 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?

The input schema already provides 100% parameter documentation, explaining IDs, slugs, comma-separated batch format, and the ALWAYS-use-batch rule. The description's batch mention adds no new semantic value beyond what the schema already covers, 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?

Uses a specific verb-resource pair ('Get complete details for businesses') and enumerates the exact fields returned (address, phone, website, hours, services, etc.). This makes the tool's scope clear and distinguishes it from search-oriented siblings like search_businesses.

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 explicit guidance on when to use this tool versus alternatives. The description and schema mention batching, but do not state when to choose get_business over search_businesses, list_categories, or get_rankings, nor provide prerequisites like needing known IDs or slugs.

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, so the safety profile is covered. The description adds unique behavioral context: rankings are based on 'real user click-through data,' which is not inferable from annotations or schema. It also mentions the area/category scope, enhancing transparency.

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

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

The description is two sentences, front-loaded with the primary action and resource. The second sentence clarifies intended usage. No filler or redundant 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?

Given the tool's moderate complexity (5 params, no output schema), the description is sufficient for an agent to select and invoke it. It explains the tool's purpose, data source, and usage context. It does not describe return format, but that is not required for a simple read-only rankings tool with clear annotations.

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

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

Schema coverage is 100%, so parameters are fully documented. The description adds a slight hint by referencing 'area' and 'category', which map to the country/city and category parameters, but it does not add syntax or format details beyond what the schema already provides. 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 clearly states the tool's function: 'Get the most popular businesses in an area, ranked by real user click-through data.' This specific verb+resource+scope distinguishes it from siblings like get_business (single business) and search_businesses (likely search-based). The additional phrase 'Use to find top-rated businesses by category' adds further specificity.

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 provides clear usage context: 'Use to find top-rated businesses by category.' This implies when you need rankings based on popularity. It does not explicitly mention alternatives or exclusions, but the sibling set and description give enough context for an agent to choose this tool over a generic search.

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 annotations already declaring readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds useful context about the return value (status and version) which is not covered by annotations or an output schema. It transparently describes the tool's behavior without contradicting 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 highly concise, consisting of three short sentences that each add value: purpose, return value, and parameter requirement. It is front-loaded with the primary action and contains no fluff.

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

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

For a simple no-parameter health check with no output schema, the description fully covers the essential information: what it does, what it returns, and that no parameters are needed. Annotations cover safety traits, making the tool contextually complete.

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

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

The tool has zero parameters and the schema description coverage is 100%, so the baseline is 4. The description reiterates that no parameters are required, but adds no additional semantic meaning since there are no parameters to explain.

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

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

The description clearly states the tool's function: checking if the discava API is online and responding. The verb 'Check' and specific resource 'discava API' make the purpose unambiguous, and it is distinct from all sibling tools which focus on data retrieval or feedback.

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

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

The description does not explicitly state when to use this tool versus alternatives. It implies usage for verifying API health, but provides no context on when to invoke it (e.g., before other calls) or any exclusions. It is minimally acceptable but lacks explicit 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 idempotentHint=true, and the description adds useful behavior: it returns all categories and includes fields like parent, implying a hierarchy. This goes beyond the safety profile, but it doesn't mention pagination or other edge cases, so a 4 is appropriate.

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

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

Two sentences, front-loaded with the core purpose and followed by a practical usage note. No wasted words; each sentence provides useful 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 no output schema, the description compensates by listing return fields (slug, translated name, parent, icon) and explains the tool's role in the broader workflow. It is complete for a simple read-only list, though it omits minor details like default language behavior, which is not critical.

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 does not add much beyond the schema's own parameter documentation—it only implies that the output slugs are useful for the category filter. It does not elaborate on lang or parent semantics, thus meets but does not exceed the baseline.

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

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

The description clearly states the action ('List') and the specific resource ('all Discava business categories'), enumerates the returned fields (slug, translated name, parent, icon), and distinguishes itself from sibling tools by explaining this is for discovering slugs to use as filters in search_businesses or get_rankings.

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

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

The description explicitly states when to use the tool: 'Call this to discover valid category slugs before using the "category" filter...' This is clear context tied to the workflow. However, it does not mention when not to use it or provide alternatives, so it misses the full 'when-not/alternatives' specificity for 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=true and idempotentHint=true, indicating a safe, non-destructive read. The description adds context by specifying the output fields (ISO code, name, flag, region) and the purpose of discovering valid country codes, which is useful beyond the annotations.

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

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

The description is two sentences: the first states the action and output fields, the second gives the usage purpose. It is concise, front-loaded, and contains no unnecessary 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?

Given the tool's simplicity, the description combined with schema and annotations covers all necessary aspects: what it returns, why to use it, and parameter details. No output schema exists, but the description mentions the return fields, so the agent can expect the result.

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

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

The input schema covers both parameters (lang, grouped) with descriptions, so schema coverage is 100%. The description does not add parameter-specific details, but with full schema coverage the baseline of 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 clearly states the tool's purpose: 'List the countries Discava supports (ISO code, name, flag, region).' It uses a specific verb ('list') and resource ('countries'), and differentiates from sibling tools like list_categories by focusing on country data.

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

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

The description explicitly tells when to use the tool: 'Call this to discover valid country codes for the required "country" parameter.' It provides a clear usage context, though it does not mention alternatives or when not to use it. Since no direct sibling alternative exists, this is sufficient.

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 establish read-only, idempotent, non-destructive behavior. The description adds the available_details pattern—telling the caller to inspect what data exists before escalating—and discloses the summary-level return shape. This is meaningful context beyond the annotations, with no contradiction.

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 the purpose and return fields front-loaded and the follow-up instruction in the second sentence. Every word earns its place and there is 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 no output schema, the description lists the key return fields and explains the available_details marker and the get_business hand-off. It does not detail score semantics or pagination behavior, but the schema covers the parameters and the workflow is complete enough for an agent to act.

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%, with every parameter described (query, category, country, lat/lon, pagination, min_confidence). The description itself does not add parameter-specific meaning, so it stays at the baseline.

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 for local businesses') and lists the return fields. It also names get_business as the full-details follow-up, which differentiates this tool's role as the search/summary entry point from the detail-retrieval sibling.

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

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

The description gives an explicit workflow: search, check available_details, then call get_business for full details. This provides clear context for the primary alternative, though it does not mention other sibling tools like list_categories or suggest.

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 indicate readOnlyHint=false and destructiveHint=false, so the tool is a write operation but not destructive. The description adds context about what to report but doesn't disclose side effects, authentication requirements, or confirmation behavior. It doesn't contradict the annotations, but it doesn't significantly enhance the behavioral picture beyond them.

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

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

The description is two sentences, front-loading the purpose and then the usage context. Every word contributes value, and it's appropriately concise for a straightforward feedback tool.

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 has no output schema and only three parameters, all documented. The description covers the purpose and when to use it. Minor gaps like what happens after submission (e.g., confirmation) aren't critical for correct invocation, making this adequate but not exhaustive.

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 each parameter (business_id, type, comment) already documented in the schema. The description adds no additional parameter semantics, 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?

The description clearly states the tool's purpose: reporting data quality issues for a business, with concrete examples of issues (incorrect phone numbers, wrong addresses, etc.). It distinguishes itself from sibling tools like get_business or search_businesses by focusing on feedback rather than data retrieval.

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

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

The description explicitly provides when-to-use guidance ('Use when you notice incorrect phone numbers, wrong addresses, outdated info, or closed businesses'), but it doesn't mention when not to use it or name alternative tools. While no sibling directly competes, explicit exclusions would make the guidance stronger.

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 establish readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is known. The description adds the behavioral context of resolving ambiguous input, but does not disclose extra traits like rate limits or response format—though the bar is lowered by 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?

Two sentences with no filler. The first sentence states the purpose and resource; the second provides a concrete usage guideline and example. Everything earns its place.

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

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

For a simple read-only autocomplete tool, the combination of a clear description, comprehensive schema, and safety annotations is sufficient. No output schema exists, but none is needed for a tool of this simplicity. One might expect a note on response format, but it is not required.

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?

All 4 parameters are fully described in the input schema (coverage 100%), so the description does not need to repeat them. The example illustrates the query parameter but adds no semantic detail beyond what the schema already 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 description uses a specific verb ('Autocomplete') and defines the exact resource ('cities or categories/business names'). It clearly distinguishes itself from sibling tools like 'search_businesses' by focusing on suggestion-style disambiguation, reinforced by the example 'Mün' → 'München'.

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 'Use before searching' explicitly tells when to use the tool, positioning it as a precursor to searching. It does not name alternatives or explicitly state when not to use it, but the intended use case is clear.

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