discava – Business Directory for AI

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds useful context about batch behavior and the returned field set, but does not disclose potential errors, rate limits, or response size considerations—acceptable given annotation coverage.

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 deliver the core purpose, field list, and batch usage with no filler. Information is front-loaded and every word contributes 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?

No output schema exists, so the description compensates by listing the fields returned (address, phone, etc.). It sufficiently explains the tool's core capabilities, though it omits details like error handling or pagination, which are less critical for a read-only retrieval.

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 100% of parameters with descriptions, including the comma-separated batch pattern and format enum. The description's mention of batch only reiterates the schema, so no additional meaning is added beyond 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 uses a specific verb ('Get') and resource ('complete details for one or more businesses'), clearly distinguishing it from siblings like search_businesses. It enumerates the returned fields and explicitly mentions batch support, making the tool's scope unambiguous.

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

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

The description implies usage by ID and explicitly directs batch calls with comma-separated IDs. It does not explicitly name alternatives or when-not-to-use, but the context is clear for a details-retrieval 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 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?

With annotations already covering read-only and idempotent behavior, the description adds useful context about the return structure, specifically the 'available_details' field indicating data existence, and the need to call another tool for full details. This goes beyond the annotations by explaining the tool's data completeness behavior.

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

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

The description is only two sentences, front-loaded with the primary action and resource, and every clause adds value. It avoids redundancy and is appropriately concise for an AI agent to parse quickly.

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

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

Given the tool has 11 parameters and no output schema, the description provides essential context about what results look like (return fields) and the follow-up action (get_business). It does not explicitly mention pagination behavior, but the schema covers page and limit parameters. Overall, it is sufficiently complete for the tool's 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?

The input schema provides descriptive text for all 11 parameters (100% coverage), so the description does not need to add parameter-level semantics. The description's mention of return fields indirectly relates to query parameters, but the schema already carries the parameter meaning burden, yielding a baseline score of 3.

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

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

The description clearly states 'Search for local businesses' with a specific verb and resource, and lists the returned fields. It also distinguishes itself from sibling tool get_business by instructing users to call get_business for full details, establishing clear purpose differentiation.

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

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

The description provides a clear usage workflow: search, check available_details, then call get_business for full details. This implies when to use this tool versus the get_business alternative. However, it does not explicitly mention when not to use it or compare with other siblings like list_categories, leaving some implicit 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 indicate readOnlyHint=false and destructiveHint=false, so the agent knows this is a write operation. The description adds context about the types of issues but doesn't disclose side effects (e.g., whether feedback is moderated, if it's one-way). It doesn't contradict annotations, but given annotations are present, the description adds only modest value beyond stating the action.

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. Every sentence adds value: the first states the core function, the second provides usage triggers. No fluff or redundancy.

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

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

For a simple tool with 3 parameters and no output schema, the description adequately covers purpose and usage context. It could mention that feedback can include suggestions (comment field) or positive confirmation, but overall it's sufficient for an agent to understand when and how to invoke 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?

Schema description coverage is 100%, so the schema already fully documents all three parameters including the enum values. The description's examples (incorrect phone numbers, wrong addresses) map to those enum values but don't add new parameter-level details. Baseline is 3 when schema covers all parameters, and no additional semantic value is provided.

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 ('Report') and a resource ('data quality issues for a business'), clearly distinguishing it from the sibling tools which are all about fetching or searching data. It unambiguously states what the tool does.

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 explicitly tells when to use the tool ('Use when you notice incorrect phone numbers, wrong addresses, outdated info, or closed businesses'). While it doesn't mention alternatives, no sibling tool serves the same purpose. It could also note that positive feedback (POSITIVE enum) is allowed, but the main use case is clearly defined.

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.