Wherobots

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

Annotations indicate readOnlyHint=true, and the description aligns with this by describing a retrieval operation ('retrieves the schema'). The description adds valuable context beyond annotations: it emphasizes the workflow importance ('ALWAYS call this before writing queries'), specifies prerequisites and next steps, and provides example usage scenarios. However, it doesn't mention rate limits, authentication needs, or error behaviors, which keeps it from a perfect score.

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 well-structured with sections (⚠️ WORKFLOW, 📋 PREREQUISITES, 📋 NEXT STEPS, Parameters, Returns, Example Usage) and uses bullet points efficiently. It's appropriately sized but includes some redundancy (e.g., repeating 'describe a specific table' and schema retrieval). Every sentence adds value, though it could be slightly more streamlined.

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 complexity (3 required parameters, 0% schema coverage, read-only operation) and the presence of an output schema (TableDescriptionOutput), the description is complete. It covers purpose, usage guidelines, parameters with examples, workflow integration, and return value explanation. The output schema handles return details, so the description doesn't need to elaborate further on the 'schema' field.

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 compensate. It explains that parameters are 'catalog', 'database', and 'table' names, and provides concrete examples (e.g., 'wherobots', 'default', 'users'). This adds clear meaning beyond the bare schema. However, it doesn't detail constraints like valid catalog/database names or length limits, leaving some ambiguity.

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 explicitly states the tool's purpose: 'retrieves the schema of a specified table, including column names and types' and 'describe a specific table.' It distinguishes from siblings by focusing on schema retrieval rather than listing (list_tables_tool), querying (execute_query_tool), or searching documentation (search_documentation_tool). The verb 'describe' and resource 'table' are specific and clear.

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 explicit guidance on when to use this tool: 'ALWAYS call this before writing queries that reference a table' and 'Understanding the schema is essential for writing correct SQL queries.' It also specifies prerequisites (call search_documentation_tool first, use list_* tools to find the table) and next steps (use generate_spatial_query_tool and execute_query_tool), clearly differentiating it from 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 only provide a title, so the description carries full burden. It extensively documents behavioral traits: workflow recommendations (test with limits), prerequisites, next steps, pagination support, JSON serialization requirement, error handling, timeout avoidance, configurable execution time/runtime/region via headers, heartbeat messages, and query cancellation on disconnect. This goes far beyond basic execution description.

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 comprehensive but lengthy with multiple sections (workflow, prerequisites, next steps, general description, reminders). While well-structured with icons and headings, it could be more front-loaded; the core purpose appears after several workflow instructions. Some redundancy exists (e.g., pagination mentioned multiple times).

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 complexity (SQL execution with multiple behavioral considerations), no annotations, and 0% schema coverage, the description provides exceptional completeness. It covers workflow, prerequisites, next steps, parameters, behavioral details, and includes an output schema description. The extensive documentation fully compensates for missing structured metadata.

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 0% schema description coverage, the description must compensate. It explains the purpose of limit ('for initial testing,' 'avoid timeouts') and offset ('for pagination'), and provides example usage showing how parameters work. However, it doesn't explicitly mention the 'ctx' parameter or provide format details for the 'query' parameter beyond SQL.

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 'execute SQL queries against the Wherobots catalog' and mentions 'data retrieval and analysis,' providing a specific verb (execute/run) and resource (SQL queries on Wherobots catalog). However, it doesn't explicitly differentiate from sibling tools like generate_spatial_query_tool or search_documentation_tool beyond mentioning them as prerequisites.

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 explicit guidance on when to use this tool ('ALWAYS test queries with this tool before generating code'), prerequisites (listing three sibling tools), and next steps based on query success/failure. It also distinguishes this as the execution step versus generation or documentation tools.

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 provide readOnlyHint=true, indicating it's a safe read operation. The description adds valuable behavioral context beyond annotations: it emphasizes a workflow dependency (must call other tools first), recommends testing with execute_query_tool, and warns to iterate if results are incorrect. This enhances transparency about usage constraints and best practices 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 front-loaded with purpose but includes extensive sections (workflow, prerequisites, next steps, examples) that, while helpful, make it verbose. Some redundancy exists (e.g., repeating example usage). It could be more streamlined while retaining key guidance, as not every sentence adds unique 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?

Given the tool's complexity (generating SQL queries), the description is complete: it covers purpose, workflow, prerequisites, next steps, and examples. With annotations indicating read-only safety and an output schema (QueryGenerationSummaryOutput) handling return values, no additional explanation of behavior or outputs is needed. It adequately addresses the context provided.

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 schema provides no parameter documentation. The description adds some semantics by explaining user_prompt as 'The user's request or description of the spatial query they want to generate' and providing example usage, but it doesn't detail format expectations (e.g., natural language vs. structured input) or constraints. This partially compensates but leaves gaps.

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 'allows user to translate their request into a spatial query' and 'Generate a spatial query based on the provided content,' which specifies the verb (generate/translate) and resource (spatial query). It distinguishes from siblings like execute_query_tool (which runs queries) and search_documentation_tool (which searches docs), but could be more precise about the output format beyond 'structured object.'

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 explicit when-to-use guidance: 'Call this ONLY after exploring docs and catalog' with a detailed workflow listing prerequisites (search_documentation_tool, catalog tools, describe_table_tool) and next steps (execute_query_tool for testing). It clearly distinguishes this tool from alternatives by positioning it as a query generation step in a larger process.

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 provide readOnlyHint=true, and the description doesn't contradict this. The description adds valuable behavioral context beyond annotations: it specifies that the tool fetches 'both managed catalogs, as well as external catalogs (e.g., on Databricks)' and mentions it's 'typically used as the first step in exploring the data hierarchy.' This provides useful operational context that annotations alone don't cover.

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 well-structured with sections (⚠️ WORKFLOW, 📋 PREREQUISITES, etc.), but it includes redundant information like 'Example Usage for LLM' and example queries that could be condensed. The core information is front-loaded, but some sentences don't earn their place, making it slightly verbose.

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 (0 parameters, read-only operation), the description is complete. It explains purpose, workflow integration, prerequisites, next steps, and behavioral details. With an output schema present, it doesn't need to detail return values, and it adequately covers all necessary context for effective use.

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 0 parameters, and schema description coverage is 100%. The description doesn't need to explain parameters, but it does mention 'ctx : Context' is 'injected automatically,' which adds clarity about the single parameter's role. For a zero-parameter tool, this exceeds the baseline expectation.

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 all catalogs available for users' and 'retrieves all available catalogs accessible with the provided API key.' It specifies the verb ('list', 'retrieves') and resource ('catalogs'), but doesn't explicitly differentiate from sibling tools like list_databases_tool or list_tables_tool beyond mentioning them in workflow context.

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 explicit guidance on when to use this tool: 'Call this after search_documentation_tool' and 'Start your catalog exploration here to discover available data sources.' It also specifies prerequisites ('Call search_documentation_tool first') and next steps (listing databases, tables, etc.), giving clear context for usage versus 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 provide readOnlyHint=true, and the description doesn't contradict this. The description adds valuable context about workflow positioning (when to call relative to other tools) and clarifies that it 'retrieves all databases' (implying completeness). However, it doesn't mention potential limitations like pagination or rate limits.

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 well-structured with clear sections (workflow, prerequisites, next steps, parameters, returns, examples). However, it's somewhat verbose - the core purpose is stated multiple times, and the example section could be more concise while maintaining clarity.

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 (1 parameter, read-only, with output schema), the description is complete. It covers purpose, workflow context, prerequisites, next steps, parameter semantics, and provides concrete examples. The output schema exists, so the description doesn't need to explain return values in detail.

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%, but the description compensates well. It explains 'catalog : str - The name of the catalog' and provides two concrete usage examples with specific catalog names ('wherobots', 'foursquare'), giving semantic meaning beyond the bare schema. The only parameter is fully documented.

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 'List all databases in a given catalog' - a specific verb ('List') and resource ('databases') with scope ('in a given catalog'). It distinguishes from siblings like list_catalogs_tool (which lists catalogs) and list_tables_tool (which lists tables).

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?

Explicit guidance is provided with '⚠️ WORKFLOW: Call this after list_catalogs_tool to explore a specific catalog' and '📋 PREREQUISITES' section naming specific tools to call first. It also includes '📋 NEXT STEPS after this tool' with explicit alternative tools for subsequent actions.

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 provide readOnlyHint=true, but the description adds valuable behavioral context: it discloses the tool is being deprecated, specifies it only shows managed catalogs (not external ones), explains what happens if catalog names don't appear, and recommends always calling list_catalogs_tool before or after. This goes beyond the safety information in 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 well-structured with clear sections (workflow, prerequisites, next steps, limitations) but contains some redundancy. Sentences like 'It can be used to retrieve information about all catalogs, list all databases within those catalogs, and enumerate all tables within each database' repeat the initial purpose. The example usage section is lengthy but provides practical 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 the tool has annotations (readOnlyHint), an output schema (explaining return structure), and 0 parameters, the description provides excellent context. It covers purpose, usage guidelines, limitations, workflow integration, and sibling tool relationships. The output schema handles return values, so the description appropriately focuses on operational context.

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 0 parameters and 100% schema description coverage, the baseline is 4. The description appropriately doesn't waste space explaining parameters, though it could mention the automatic context injection more explicitly. The focus remains on the tool's behavior rather than parameter details.

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: 'Get complete hierarchy of catalogs, databases, and tables' and 'provides a comprehensive view of all available assets in the Wherobots system, including their hierarchical relationships.' It distinguishes from siblings by specifying this is for 'managed catalogs' only, unlike list_catalogs_tool for external catalogs.

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 explicit guidance: 'Use this for a quick overview of all managed catalogs' and 'For external catalogs, use list_catalogs_tool instead.' It includes prerequisites (call search_documentation_tool first) and next steps (use describe_table_tool, list_catalogs_tool). The 'IMPORTANT LIMITATION' section further clarifies when to use 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 provide readOnlyHint=true, which the description doesn't contradict. The description adds valuable context about the tool's role in the data hierarchy and workflow dependencies, though it doesn't mention rate limits, authentication needs, or error behaviors beyond what annotations cover.

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 core purpose but includes extensive sections (workflow, prerequisites, next steps, parameters, returns, examples) that add value but reduce conciseness. Some information (like the Returns section) is redundant given the output schema.

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 complexity (2 parameters, workflow dependencies), the description is highly complete. It covers purpose, usage sequence, parameters, returns, and examples. With annotations and an output schema, no critical gaps remain for effective agent use.

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%, but the description explicitly defines both parameters (catalog and database) in the Parameters section and provides example usage. However, it doesn't add semantic details like format constraints or examples beyond basic naming, so it partially compensates for the schema 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?

The description clearly states the specific action ('List all tables') and resource ('in a given database'), and distinguishes it from siblings by positioning it as the final level in the data hierarchy before accessing table schemas. The title reinforces this purpose.

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?

Explicit guidance is provided with workflow instructions ('Call this after list_databases_tool'), prerequisites (calling search_documentation_tool, list_catalogs_tool, and list_databases_tool first), and next steps (describe_table_tool, generate_spatial_query_tool, execute_query_tool). It clearly establishes when to use this tool in sequence.

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, indicating a safe read operation. The description adds valuable behavioral context beyond annotations: it specifies this is for searching 'official Wherobots documentation,' provides workflow sequencing guidance, and references external documentation links. However, it doesn't mention rate limits, authentication needs, or pagination behavior beyond the page_size parameter.

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 well-structured with clear sections (workflow, next steps, parameters, returns, examples) but is overly verbose. It includes redundant information (repeating the tool's purpose multiple times) and extensive example sections that could be condensed. The external documentation links at the end add value but could be integrated more efficiently.

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, annotations covering safety, and an output schema defining DocumentationSearchOutput, the description is mostly complete. It explains the tool's role in the workflow, provides usage examples, and references external resources. However, it could better explain how search results are ranked or filtered, and the parameter semantics section has some gaps despite the output schema existing.

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 0% schema description coverage, the schema provides no parameter documentation. The description adds some semantic context: it explains 'query' is a 'search query string' and 'page_size' is 'Optional number of results to return (default: 10).' However, it doesn't provide guidance on query formulation, result ranking, or what 'ctx' parameter does beyond 'injected automatically,' leaving gaps in parameter understanding.

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: 'Search the Wherobots documentation' and specifies it's for finding 'information about spatial functions, data formats, best practices, and more.' It distinguishes from siblings by focusing on documentation search rather than data catalog exploration or query execution, with explicit differentiation in the workflow section.

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 explicit guidance on when to use this tool: 'This should be your FIRST tool call for any query task' and 'Before writing queries, ALWAYS search documentation.' It offers clear alternatives by listing next steps with specific sibling tools (catalog tools, describe_table_tool, generate_spatial_query_tool) and provides example user queries with corresponding tool calls.

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