Baselight

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

Annotations already declare readOnlyHint and openWorldHint. Description adds valuable context: naming conventions for dataset and table identifiers, and double-quoted SQL identifiers. 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 sentences, each with clear purpose: first defines action, second provides usage context and naming details. No filler, well-structured.

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 one parameter and no output schema, the description addresses purpose, usage context, and naming conventions. Could optionally mention that it returns schema details like column names and types, but overall sufficient for agent decision-making.

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?

Single parameter 'id' with schema description already includes example format '@user.dataset'. Description reinforces this, adding clarity without redundancy. Schema coverage is 100%, so the description adds marginal but sufficient value.

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 the verb 'Retrieve' and resource 'detailed schema and metadata for a specific dataset', with explicit format (@username.dataset). Distinguishes from siblings like baselight_get_dataset_tables and baselight_get_table_metadata by focusing on overall dataset structure.

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?

Provides usage context: 'Use this after discovering datasets to understand their structure before querying.' Implies sequence, but does not explicitly exclude other tools or state when not to use.

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 declare readOnlyHint and openWorldHint. The description adds useful behavioral details: pagination, page limit of 100 tables, and metadata inclusion. 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?

Two sentences with no waste. The main action is front-loaded, and every sentence adds value (usage context, pagination detail).

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?

Without an output schema, the description partly compensates by mentioning metadata is returned. It covers purpose, parameters, and pagination. Could specify metadata fields, but adequate for a list 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 coverage is 100%, so the description adds little beyond repeating schema info (e.g., id format). It does not elaborate on query or page semantics beyond defaults, so 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), resource (tables from a specific dataset), and required format (@username.dataset), distinguishing it from siblings like search_tables and get_table_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 provides explicit use cases: browsing datasets with many tables or searching for specific tables. It lacks explicit when-not-to-use guidance or alternatives, but the context is clear given sibling 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 declare readOnlyHint=true, so the description adds value by specifying the return content (schema, metadata, column types, constraints). It does not contradict annotations and provides additional behavioral context about the expected format and SQL quoting.

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 that deliver essential information without fluff. Every sentence earns its place: purpose, usage context, and a critical usage hint. 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 single-parameter read-only tool with no output schema, the description covers all necessary aspects: what it returns, when to use it, and formatting guidance. The agent has everything needed to select and 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 coverage is 100% with a clear description of 'id', but the tool description goes beyond by reiterating the format (@username.dataset.table) and adding the practical constraint that tables must be referenced in SQL with double quotes. This adds meaning for the agent.

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', making the tool's purpose unambiguous. It implicitly distinguishes from siblings like baselight_get_dataset_metadata (dataset-level) and baselight_search_tables (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 explicitly says to use this tool to understand table structure before writing SQL queries, providing clear context. While it does not list exclusions or alternatives, the sibling tool list implies other options, and the usage guidance is strong enough for an agent to decide.

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 and openWorldHint. The description adds context about the data returned (bio, website, datasets) but does not detail behavior like error handling or response format.

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: first defines the tool's action and returns, second provides usage context. No 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 simplicity (single required param, read-only), the description covers purpose, content, and when to use. Minor gaps: no mention of error cases or response format, but not critical for a 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?

The single parameter 'username' has a clear schema description. The tool description does not add further semantics beyond implying the parameter's purpose, but with 100% schema coverage, baseline is adequate.

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, listing specific attributes (profile bio, website, public datasets). It effectively distinguishes from siblings focused on datasets and 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 ('understand who owns datasets you're interested in') but lacks explicit when-not-to-use or alternative tools. No exclusionary guidance is given.

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?

Beyond annotations (readOnlyHint, openWorldHint), the description adds that the tool polls for up to 1 minute if the query is still pending, returning results immediately if complete. No contradiction 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 three sentences, front-loading the main purpose, with each sentence adding essential information. 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?

The description explains the polling behavior and condition for immediate return. However, it does not describe the format of returned results (e.g., JSON structure, rows). With no output schema, a bit more detail would help.

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 description adds context that jobId comes from `sdk-query-execute`, but since schema coverage is 100% with descriptions for all three parameters, the added value is minimal, staying at the baseline.

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

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

The description clearly states the tool retrieves results from a previously executed SDK job using the resultId. It links to `sdk-query-execute`, which distinguishes it from sibling tools that deal with metadata, users, or searches.

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 advises using this tool after `sdk-query-execute` returns PENDING status and describes polling behavior. However, it lacks explicit when-not-to-use guidance or alternative tool mentions.

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 discloses important behaviors like waiting up to 1 minute, returning first 100 rows, and handling pending queries. However, there is a contradiction with annotations: readOnlyHint=false while the description restricts to SELECT queries only (read-only). This inconsistency reduces the 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 concise, front-loaded with the main action, and every sentence provides specific, non-redundant instructions. No filler or 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 simple input schema (1 param, no output schema), the description thoroughly covers behavior, including edge cases (pending queries, pagination) and references to sibling tools for follow-up actions.

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 sole parameter 'sql' has a schema description that already covers basic constraints. The description adds valuable extra context (no semicolon, LIMIT not TOP, double quotes) but repeats some schema information. With 100% schema coverage, the description still adds meaningful guidance.

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, specifying the wait time and row limit. It distinguishes itself from sibling tools like sdk-get-results by explicitly mentioning when to use them for polling and 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?

The description gives explicit instructions on when to use this tool versus alternatives: if the query is PENDING, use sdk-get-results; if more rows are needed, use sdk-get-results with offset. It also specifies required syntax (DuckDB, double-quoted tables, SELECT only, no semicolons, LIMIT not TOP).

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 valuable behavioral context: datasets follow a specific format (@username.dataset), and both public and user's private datasets are searchable. 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?

The description is concise with three sentences, no wasted words. The key information (search, first step, dataset format) is front-loaded. 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?

Given no output schema, the description does not explain return values, but for a search tool this is acceptable. It covers the core purpose, usage context, and dataset naming convention. Could mention pagination or result structure, but the sibling tools cover 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?

Input schema has 100% description coverage. The tool description adds minimal additional meaning: it specifies that query is 'used for semantic search' and implies category filters. This adds a bit of context beyond the schema, but not substantial.

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 the catalog for datasets using a text query and filters. It specifies the verb 'Search', the resource 'catalog datasets', and distinguishes from siblings like 'baselight_search_tables' by focusing on datasets. The naming format and visibility information adds clarity.

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 this is 'typically the first step in the discovery workflow,' guiding when to use it. It does not explicitly state when not to use it or compare to alternatives, but the context is clear enough for an AI agent.

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 and openWorldHint. The description adds useful behavioral context about public/private dataset access and table format, enhancing transparency 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 three sentences, each serving a purpose: stating the action, explaining the table format, and providing usage context. It is front-loaded and efficient, though 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's moderate complexity (3 parameters, no output schema), the description covers the data model, search scope, and when to use. It does not explain return format, but that is acceptable for a search tool with no output schema.

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 mentions 'text query and filters' but does not add meaning beyond what the schema descriptions (e.g., 'semantic search' for query, limit range, category enum) already provide.

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 text and filters, and explains the table naming convention and dataset grouping. It distinguishes itself from sibling tools like baselight_search_catalog by advising direct table search when datasets cannot be 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?

Provides explicit guidance: 'Search for tables directly when you are unable to find relevant datasets.' This implies when to use it versus dataset search, though it does not list when not to use or alternative tools explicitly.

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