Baselight

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

Annotations (readOnlyHint, openWorldHint) cover safety and open-world assumptions. Description adds identifier format detail but does not disclose additional behavioral traits like error handling, pagination, or cost, which is 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: first states purpose, second adds usage guidance. No filler or repetition. Front-loaded and efficient.

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, but description gives reasonable expectation ('detailed schema and metadata'). Includes naming convention for tables. Could be more specific about return structure, but adequate for a 1-parameter retrieval 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 already describes id parameter; description adds concrete format example ('@user.dataset'), enhancing understanding beyond the schema definition. Coverage is 100% so baseline is 3; the example pushes it to 4.

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?

Clearly states the action (retrieve) and resource (schema and metadata for a specific dataset). Distinguishes from sibling tools like baselight_get_dataset_tables (tables only) and baselight_get_table_metadata (table-level).

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

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

Explicitly says 'use this after discovering datasets to understand their structure before querying', providing a clear usage context. Also mentions table naming convention and SQL identifier style, though no when-not-to-use alternatives listed.

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 provide readOnlyHint and openWorldHint. The description adds behavioral details such as pagination (up to 100 tables per page) and optional query filtering, 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?

Two sentences with no fluff: the first clearly states the purpose, the second explains usage and pagination limit. Every sentence 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?

Covers pagination and optional search adequately for a list tool, though it lacks details on return format. The openWorldHint annotation compensates somewhat, but with no output schema, a brief mention of response fields would improve completeness.

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 baseline is 3. The description reinforces the format for 'id' and the purpose of 'page' and 'query', but does not add significant new parameter-level details beyond the schema descriptions.

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 ('retrieve'), resource ('list of tables'), and context ('from a specific dataset using Baselight format @username.dataset'), clearly distinguishing it from sibling tools like baselight_search_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?

Explicitly states to use this tool for browsing datasets with many tables or searching for specific tables, but does not mention when not to use it or alternatives like baselight_search_tables.

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 read-only; description adds value by specifying the Baselight format and quoting requirement. Does not cover response structure or rate limits, but sufficient given 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 front-loaded purpose, no wasted words.

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?

Provides a high-level summary of returned information (structure, column types, constraints) but lacks precise field listing due to no output schema. Still adequate for expected usage.

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% and schema description already covers the id parameter format. Description adds minimal extra value beyond schema.

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

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

Description clearly states verb ('retrieve') and resource ('detailed schema and metadata for a specific table'), and distinguishes from sibling tools like baselight_get_dataset_tables and baselight_get_dataset_metadata.

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?

Advises using the tool before writing SQL queries and specifies the table referencing format with double quotes, but does not explicitly exclude cases or name alternative 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 already indicate readOnlyHint=true and openWorldHint=true. The description adds context about the specific data returned (bio, website, public datasets), which goes beyond the annotations. No contradictions.

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 concise sentences, front-loaded with the main purpose, followed by a use-case. No extraneous 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 simple retrieval tool with one parameter and useful annotations, the description adequately covers purpose and usage. It lacks explicit mention of response format, but given no output schema, this is acceptable.

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 100% schema description coverage for the single parameter, the baseline is 3. The description does not add additional meaning to the 'username' parameter beyond what the schema 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 clearly states the tool retrieves detailed information about a Baselight user, including specific fields like profile bio, website, and public datasets. The verb 'retrieve' and resource 'user' are precise, and it naturally distinguishes from sibling tools focused on datasets.

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 says 'Use this to understand who owns datasets you're interested in,' providing a clear use case. It doesn't mention when not to use it or alternatives, but given the sibling tools, the context 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 declare readOnlyHint=true, indicating no side effects. The description adds that it is simple and verifies server response, fully disclosing 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?

Single, front-loaded sentence with no wasted words. It is appropriately sized for a simple ping 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?

Given the tool's simplicity, no output schema, and perfect annotations, the description is complete and does not require additional details.

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?

No parameters exist, so baseline score of 4 applies as per rules. Description adds no param info, which 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 it is a ping test to verify server responsiveness, using specific verb and resource. This distinguishes it from sibling tools that deal with datasets and users.

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?

While no explicit when/when-not or alternatives are provided, the context and name make it obvious this is for connectivity checks. It is safe to assume it's the only health check 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 provide `readOnlyHint` and `openWorldHint`, and the description adds concrete polling behavior (up to 1 minute) and the condition for immediate returns. 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 concise sentences, front-loaded with the main purpose, and no unnecessary verbiage. Every sentence adds 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?

Completeness is adequate: covers retrieval, polling, pagination parameters, and prerequisite. No output schema, but the tool returns results; description doesn't specify output format, which is acceptable given typical expectations.

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%, and the description adds context about `jobId` being from `sdk-query-execute`, enhancing the schema's minimal descriptions.

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 specifies retrieving results from a previously executed SDK job using the resultId, stating the verb ('Retrieve') and the resource ('results from a previously executed SDK job'), and distinguishes from siblings by referencing the prerequisite tool `sdk-query-execute`.

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

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

Explicitly states when to use this tool: after `sdk-query-execute` returns PENDING status. Mentions polling behavior but does not explicitly state when not to use it or list alternative tools, though the sibling context implies the workflow.

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?

Discloses behavioral traits beyond annotations: waits up to 1 minute, returns first 100 rows, can return pending status. Does not contradict annotations; adds context that annotations alone do not provide.

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?

Description is a single paragraph with clear front-loading of purpose. Every sentence adds value, though it could be slightly more concise. Structure is logical, moving from purpose to constraints to follow-up actions.

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 no output schema, description explains return format (first 100 rows, pending info, totalResults). Covers error/edge cases: pending query, pagination needs. Full coverage for a single-parameter 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 baseline is 3. Description adds value by reiterating syntax requirements and providing examples (e.g., double-quoted table identifiers). Adds restrictions like no semicolons, use LIMIT. Slightly above 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?

Clearly states it executes a SQL query on Baselight and waits for results, specifying the verb 'Execute' and resource 'SQL query'. Distinguishes from sibling tools like sdk-get-results by describing polling and pagination behavior.

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

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

Explicitly tells when to use this tool vs alternatives: if query pending, use sdk-get-results; for more rows, use sdk-get-results with offset. Also provides specific syntax constraints (DuckDB, SELECT only, no semicolons, use LIMIT).

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=true, indicating safe read and unbounded results. The description adds value by explaining dataset format (@username.dataset), public/private access, and that it returns datasets. No contradictions.

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?

Three sentences: first states purpose, second adds dataset format and access, third gives usage context. No unnecessary words, front-loaded, efficient.

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 search tool with 3 well-documented parameters and no output schema, the description covers key aspects: purpose, naming convention, access control, and usage step in workflow. Missing details on output format, but given readOnlyHint and openWorldHint, it is reasonably 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?

Schema description coverage is 100%, so baseline is 3. The description mentions 'text query and filters' but does not elaborate beyond what the schema already provides for each parameter. The added context about dataset naming is not parameter-specific.

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?

Description clearly states verb 'search' and resource 'catalog for datasets'. It adds context about dataset naming format and access, but does not explicitly differentiate from sibling tool 'baselight_search_tables', which likely targets tables. Implicitly distinguishes by specifying datasets.

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 clear usage context: 'typically the first step in the discovery workflow'. This indicates when to use it. However, it does not explicitly state when not to use it or mention alternative sibling tools like 'baselight_search_tables'.

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=true and openWorldHint=true. The description adds context about table format ('@username.dataset.table') and search scope (public and user's private datasets). This explains the data coverage 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 concise with three sentences. The first states purpose, the second explains format and scope, and the third guides usage. No unnecessary details.

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 search tool with 3 parameters and no output schema, the description explains search scope, table format, and when to use it. It lacks details about the response format but is adequate for an agent to invoke the 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 description coverage is 100%, so the schema already provides good parameter descriptions. The description adds context about table format and datasets but does not enhance parameter meaning beyond what is in the schema.

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

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

The description clearly states the tool's purpose: 'Search for tables using a text query and filters.' It specifies the search scope (all public datasets and user's private datasets) and distinguishes from dataset search by suggesting use when datasets are not found.

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 use case: 'Search for tables directly when you are unable to find relevant datasets.' It explains that tables are grouped into datasets and which datasets are searchable. While it doesn't explicitly exclude scenarios, the context is sufficient for an agent to decide when to use this tool.

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