baselight

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

The description is consistent with annotations (readOnlyHint, openWorldHint). It adds useful context about table identifier format ('@username.dataset.table' with double-quoted SQL identifiers), which aids understanding of the tool's behavior beyond what annotations 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?

Two sentences with no redundancy. The first sentence covers purpose and format; the second adds usage guidance and a key naming convention. Every sentence 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 metadata retrieval tool with readOnlyHint and no output schema, the description provides essential information: what it does, when to use it, and a critical naming rule for tables. It could be slightly more specific about what 'detailed schema and metadata' includes, but overall it's complete enough.

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 schema already thoroughly describes the single required parameter 'id' with format hint '@user.dataset'. The description reinforces this format but doesn't add significant new semantic meaning beyond the schema, which has 100% coverage.

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 verb 'retrieve' and the resource 'detailed schema and metadata for a specific dataset'. It uses the specific format @username.dataset, distinguishing it from siblings like baselight_get_dataset_tables which focus on tables within a dataset.

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 the tool: 'Use this after discovering datasets to understand their structure before querying.' This provides clear context for usage, though it doesn't explicitly mention when not to use it or 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?

The description adds behavioral details beyond the readOnlyHint and openWorldHint annotations, such as pagination (up to 100 tables per page), dataset identifier format, and optional filtering. No contradictions with 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 clear, front-loaded sentences with no wasted words. Every sentence contributes value: first defines purpose, second explains usage and pagination.

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 description covers the main aspects: pagination, filtering, dataset format. It does not detail what metadata is returned per table, but given no output schema, this is acceptable. Minor gap for a fully complete picture.

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 meaning beyond the schema; it simply restates the id format and page default. The pagination info is more about tool behavior than parameter semantics.

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 (retrieve a paginated list), the resource (tables from a specific dataset), and the required format (@username.dataset). It distinguishes from siblings like baselight_get_dataset_metadata and 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?

The description explicitly says when to use this tool: 'to browse datasets with many tables or to search for specific tables within a dataset.' It implies when not to use it based on sibling tools, but does not explicitly list 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 already declare readOnlyHint=true and openWorldHint=true, indicating safe read operation. The description adds valuable behavioral context by stating what is returned: 'schema, column types, constraints'. It does not contradict 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 purpose and format, the second provides usage context and a practical SQL quoting rule. It is front-loaded and contains no unnecessary 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?

For a simple tool with one parameter and no output schema, the description covers the essential aspects: purpose, input format, usage context, and a practical tip. It could explicitly list what metadata is returned (e.g., columns, types, constraints) but already mentions 'column types and constraints'.

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 a clear description of the 'id' parameter. The overall description repeats the format '@username.dataset.table' but adds no new semantic detail beyond what the schema provides. Baseline score is 3 given full schema coverage.

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 verb 'Retrieve' and the resource 'detailed schema and metadata for a specific table'. It distinguishes this tool from siblings like baselight_get_dataset_metadata (dataset-level) and baselight_get_dataset_tables (list tables) by focusing on a single table.

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 context for when to use the tool: 'Use this to understand table structure... before writing SQL queries.' It implies this is for initial exploration. While it does not explicitly mention when not to use it, the context is clear and references the specific table format.

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?

The description's 'retrieve' aligns with annotations (readOnlyHint, openWorldHint). It adds detail on what's included (profile, website, public datasets) but does not significantly expand beyond the annotations' safety and openness signals.

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 with no wasted words. It front-loads the action and resource, then provides usage context 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?

For a simple single-parameter tool with no output schema, the description covers purpose and usage. It lacks error handling or failure scenarios (e.g., user not found), but overall it is adequate.

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 has 100% coverage with a description that matches the tool's purpose. The description adds no extra meaning beyond the schema's 'username of the user to inspect.'

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 profile bio, website, and public datasets. The verb 'retrieve' is specific and the resource 'user' is distinct from sibling tools like dataset metadata or table search.

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: 'to understand who owns datasets you're interested in.' It implies context but does not explicitly state when not to use the tool or list alternatives among siblings.

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, so the description needs to add little beyond that. It confirms the non-destructive nature but does not elaborate on response or other behaviors.

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 sentence, no extraneous information. Perfectly concise.

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 ping tool with no parameters, the description is fully adequate. No output schema needed; the tool's behavior is trivial.

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 the description has no additional burden. Baseline score of 4 applies as schema coverage is 100%.

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 a simple ping test to verify server responsiveness, using a specific verb and resource. It uniquely distinguishes itself from sibling tools which are all data-related operations.

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?

No usage guidelines are needed for a ping test; its purpose is self-evident and there are no alternatives among siblings.

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?

The description adds significant behavioral context beyond annotations: it reveals polling logic, immediate return if complete, and 1-minute timeout. Annotations already indicate read-only and open-world, which are consistent.

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 (3 sentences) and front-loaded with the core purpose. Every sentence is informative, and 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?

Given the tool's simplicity (3 params, no nested objects, no output schema), the description adequately covers behavior and usage. It could mention the result format or pagination tips, but overall it is complete enough 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?

Schema coverage is 100% with detailed descriptions for each parameter. The description does not add extra parameter semantics beyond what the schema provides, but it correctly references jobId in context. Baseline 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 verb 'Retrieve results' and the resource 'previously executed SDK job'. It distinguishes from the sibling `baselight_sdk_query_execute` by mentioning the resultId and the use after PENDING status.

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 instructs when to use the tool: 'Use this after `sdk-query-execute` returns PENDING status.' Also describes the polling behavior and max wait time, providing clear context for invocation.

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 key behaviors: waits up to 1 minute, returns first 100 rows or pending info, syntax restrictions, and instructions for polling/pagination. Annotations have readOnlyHint=false and destructiveHint=false, which are consistent with SELECT-only constraint. 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?

Concise single paragraph, front-loaded with purpose and constraints, then fallback instructions. Every sentence is essential—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?

Comprehensive for a query execution tool: explains what it does, syntax rules, error handling (pending), and continuation mechanisms (polling, pagination). No output schema, but return behavior is adequately described (100 rows, pending info).

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?

Only one parameter 'sql' with schema description covering basics. The description adds extra constraints (table format, no semicolons, LIMIT vs TOP) that are not in the schema description. Schema coverage is 100%, so baseline is 3; the extra context raises 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?

The description clearly states the tool executes a SQL query on Baselight and waits for results. It specifies the verb 'Execute', resource 'SQL query on Baselight', and key behavior like 1-minute wait and 100-row return. It distinguishes from sibling sdk-get-results by mentioning polling for pending or pagination.

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 guidelines: use for SQL queries only, SELECT only, DuckDB syntax, table format '@username.dataset.table' double-quoted, no semicolons, LIMIT not TOP. Also specifies when to use sdk-get-results (if pending or need more rows). Provides alternatives for pagination and polling.

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, so the description's job is lighter. It adds useful behavioral context: datasets have a specific format and visibility rules (public vs. private). However, it doesn't detail pagination or result structure.

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, no wasted words. The first sentence states the action, the second provides essential context about dataset format and typical use case. Highly 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?

Given the tool's moderate complexity and the absence of an output schema, the description covers the key aspects: what is searched, the format of datasets, and the typical workflow. It could elaborate on return format, but sibling tools fill the gap (e.g., baselight_get_dataset_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?

Schema description coverage is 100%, so the baseline is 3. The description adds the dataset format context, which indirectly aids in understanding parameter usage (e.g., query is a text search), but doesn't significantly enhance parameter semantics beyond 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 the catalog for datasets using a text query and filters.' It also explains the dataset format and visibility, distinguishing it from sibling tools like baselight_search_tables or 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?

The description mentions that this is 'typically the first step in the discovery workflow,' giving clear usage context. It does not explicitly state when not to use it or name alternatives, but the implied workflow guides the agent effectively.

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?

The description adds useful behavioral context beyond the annotations: it explains table naming convention, public/private dataset access, and search scope. It aligns with the readOnlyHint and openWorldHint annotations without 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?

The description is concise with three sentences, focusing on essential information. It is well-structured and front-loaded, though it could be slightly more compact.

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 3 parameters, annotations, but no output schema, the description provides adequate context about scope and naming. However, it lacks details about result format, pagination, or ordering, which would help an agent use the tool more effectively.

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 the baseline is 3. The description does not add significant meaning beyond the schema; it simply mentions 'text query and filters' which mirrors the parameter names. No elaboration on parameter usage 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 clearly states the tool searches for tables using a text query and filters, and explains the table format. It hints at when to use it ('directly when you are unable to find relevant datasets'), providing some differentiation from sibling search tools like baselight_search_catalog, but could be more explicit.

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 a usage scenario (when datasets are not found) but does not explicitly state when not to use this tool or list alternatives. It provides only indirect guidance on when it is appropriate.

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