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

The description confirms a write operation ('Create'), which aligns with annotations (readOnlyHint: false). It does not add behavioral details beyond the annotation, such as permission requirements or side effects. Since annotations already disclose the non-read-only nature, this is adequate but not enriched.

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, front-loaded with the action, and no wasted words. Every phrase adds value, covering purpose and use cases 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 create tool with full schema parameter descriptions and an output schema, the description provides sufficient context. It covers what the tool does, when to use it, and use cases, leaving no critical gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All 5 parameters are described in the schema (100% coverage), so the baseline is 3. The description adds no additional parameter-specific 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?

Description clearly states verb+resource: 'Create a new Metabase dashboard.' It then provides specific use cases ('build new analytical views, organize related cards, or establish monitoring interfaces'), which distinguishes it from sibling tools like list_dashboards and get_dashboard that are read-only.

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 clear contexts for use ('build new analytical views, organize related cards, or establish monitoring interfaces'), implying when to use it. However, it does not explicitly mention alternatives or when not to use it, leaving differentiation to the sibling tool names.

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 annotation readOnlyHint=true already signals a safe read operation. The description adds that it returns 'actual data results', but does not disclose caching behavior, permission requirements, or execution impact. With annotations covering safety, the description provides only marginal additional behavioral context.

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 a single, well-structured sentence that front-loads the primary action and then lists three concrete use cases. There is no superfluous information; every phrase 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?

The tool has an output schema, so return values need no explanation. The description covers the core purpose and usage context. While it does not elaborate on the dashboard_id or ignore_cache parameters, the schema descriptions handle those. The description is adequately complete for a moderately complex 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% and each parameter (card_id, dashboard_id, ignore_cache, collection_preview) already has meaningful descriptions. The tool description does not add parameter-specific semantics, so it stays at the baseline 3 where the schema carries the burden.

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 runs a Metabase card query and returns actual data results, using a specific verb ('Run') and resource ('card query'). It distinguishes from siblings like get_card (metadata) and execute_query (likely raw SQL) by emphasizing returning the actual data.

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

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

The description explicitly lists use cases: 'to get current data from existing cards, refresh analytical insights, or programmatically access query results'. It does not mention when not to use it or name alternatives, but the use cases are clear and contextual enough for an agent to select it.

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 annotation readOnlyHint=true already establishes that this is a read operation, so the description doesn't need to restate that. The description adds some context about purpose but does not disclose additional behavioral traits such as potential performance implications, result size limits, or permission requirements. With annotations present, a score of 3 is appropriate as it provides minimal added behavioral context.

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 a single sentence that is concise and front-loaded with the main action. It conveys purpose and usage efficiently without unnecessary verbosity. However, it could be split into two sentences for slightly better readability, so a score of 4 rather than 5.

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 tool is moderately complex (arbitrary SQL execution) and has an output schema that explains return values. The description covers the core purpose and when to use it, which is sufficient for an agent to select the tool. It doesn't mention potential caveats like query safety or runtime, but annotations and output schema fill some gaps. Overall, it is contextually complete enough for most use cases.

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% parameter description coverage, with descriptions for query, parameters, and database_id. The tool description does not significantly add meaning beyond the schema, though it reinforces that the query is 'native SQL'. Since the schema already carries the burden, baseline 3 is justified.

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

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

The description uses a specific verb ('Execute') and clearly identifies the resource ('native SQL query against a Metabase database'). It also explains the intended use cases (custom data analysis, complex queries, extracting data not available through existing cards), which distinguishes it from sibling tools like execute_card and get_table_data.

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

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

The description provides clear context on when to use this tool, explicitly mentioning 'custom data analysis' and 'complex queries'. It also implies an alternative ('not available through existing cards') which suggests using saved cards for standard needs, though it doesn't name the exact sibling tool. There is no explicit 'when not to use' statement.

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

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

With readOnlyHint=true already present, the description adds value by detailing what metadata is returned (query definition, visualization settings, collection location, permissions). This gives the agent a clearer picture of the tool's output scope and what it can learn from the card. It does not add caveats about rate limits or auth, but for a read-only metadata fetch, this is adequate.

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 a single, well-structured sentence that leads with the main action and then lists details. No redundant words or repeated schema information. It is perfectly concise and front-loaded.

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

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

For a simple read-only tool with one parameter and an output schema, the description covers the essential purpose and return content. The sibling tool names provide additional context (e.g., execute_card vs. get_card). The description is complete enough for an agent to select and invoke the tool correctly without additional information.

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 describes card_id as 'Card ID', and the description does not add further semantic detail beyond 'specific Metabase card'. Since schema coverage is 100% and there is only one simple parameter, the baseline of 3 is appropriate; the description contributes minimal additional 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 tool 'Get complete metadata and configuration for a specific Metabase card' and enumerates the included aspects (query definition, visualization settings, collection location, permissions). This distinguishes it from siblings like execute_card (which runs the card) and list_cards (which lists cards). The verb and resource are specific and unambiguous.

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

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

The description provides clear context: 'use this when you need to examine or understand how a particular card is built.' This implies the appropriate use case for inspection rather than execution or listing. It does not explicitly name alternatives or exclusions, but the guidance is sufficient given the sibling tool names and the tool's read-only nature.

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 annotation readOnlyHint=true already signals a safe read operation, lowering the bar for additional behavioral disclosure. The description adds no extra context beyond purpose, such as error handling, output format details, or dependency behavior. It does not contradict the annotation.

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 one sentence with a clear front-loaded verb and resource, followed by three concrete use cases. Every phrase earns its place, and there is no redundancy or padding.

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 an output schema, the description covers the core purpose and practical use cases. It lacks explicit mention of edge cases (e.g., behavior if card does not exist), but the output schema and readOnly annotation mitigate any ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers the single parameter card_id with the description 'Card ID' (100% coverage). The tool description adds no further semantic detail about the parameter, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool finds all dashboards that include a specific Metabase card, using a specific verb ('Find') and explicit resource ('dashboards') with a qualifying relationship to a card. It distinguishes itself from siblings like list_dashboards (which lists all dashboards) and get_dashboard_cards (which lists cards in a dashboard).

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: 'understand where a card is being used, track dependencies before making changes, or find related analytical content'. It does not name alternative tools or state when not to use, but the context is clear and actionable.

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 readOnlyHint annotation already communicates the safe read-only nature, and the description adds that the items are cards and dashboards. However, it does not disclose behavior such as pagination, sorting, or whether subcollections are included, though the output schema may cover return 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?

The description is a single, front-loaded sentence that immediately states the action and resource, followed by concise use cases. No redundant information or filler.

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 one-parameter schema, output schema, and read-only annotation, the description provides adequate context by specifying item types and use cases. It could mention pagination or subcollection behavior, but the tool's simplicity keeps this from being a significant gap.

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 fully describes the only parameter (collection_id), so the description adds no new meaning beyond implying the collection context. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool retrieves all items (cards, dashboards) within a Metabase collection, using a specific verb and resource. This differentiates it from sibling tools like list_cards or list_dashboards, which operate at a broader scope.

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 use cases: exploring collection contents, organizing analytical assets, or understanding content structure. It does not explicitly name alternatives or exclusions, but it implies the tool is for collection-scoped retrieval, which is sufficient context.

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 safety profile is covered. The description adds the type of information returned (cards, layout, settings), but this may overlap with the output schema. No additional behavioral traits (auth, rate limits, side effects) are disclosed, making this a minimal but acceptable addition beyond 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 a single, well-structured sentence that front-loads the action and outcome. It is concise, informative, and every word adds value with no 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?

Given the simplicity (one required parameter), read-only annotation, and presence of an output schema, the description adequately covers the tool's purpose and usage. The agent has enough context to invoke and interpret the response without needing further 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?

Schema coverage is 100%, with a single required parameter 'dashboard_id' described as 'The ID of the dashboard to retrieve.' The description adds 'specific dashboard' but doesn't provide further syntax or format details beyond the schema, so it meets the baseline but doesn't exceed it.

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 specific Metabase dashboard, listing contents (cards, layout, settings). This distinguishes it from sibling tools like list_dashboards (which lists all dashboards) and get_dashboard_cards (which likely retrieves just cards), providing a specific verb+resource+scope.

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 clear usage context: 'use this to examine dashboard structure or get configuration details' and specifies 'a specific Metabase dashboard,' implying use when you have a dashboard ID. It does not explicitly exclude alternatives like list_dashboards, but the context is sufficient for an AI agent to select it appropriately.

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 annotation readOnlyHint=true already discloses the safety profile. The description adds context about returning all cards and typical use cases, but it does not elaborate on return structure, pagination, or any further behavioral details. Given the annotation exists, this is acceptable but not exhaustive.

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 a single, well-structured sentence that immediately states the core function and typical use cases. There is no redundant phrasing or filler.

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 tool has a single parameter with full schema coverage and an output schema that defines return values. The description sufficiently explains the tool's purpose and usage context for a straightforward read-only operation, so no additional details are needed.

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 describes dashboard_id as 'The ID of the dashboard' with 100% coverage. The description reinforces the concept of a specific dashboard but does not add additional meaning beyond the schema. Baseline of 3 applies.

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

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

The description clearly states the action ('Retrieve') and the resource ('all cards within a specific Metabase dashboard'), distinguishing it from sibling tools like get_card (single card) or list_cards (potentially all cards). It also specifies the scope (specific dashboard) and intention (analyze content, understand data sources, examine configurations).

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 provides use cases ('use this to analyze dashboard content, understand data sources, or examine card configurations'), giving clear context for when to use the tool. It does not mention exclusions or alternative tools, but the context is sufficient for a simple read-only 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?

The annotation readOnlyHint=true already establishes safety, and the description's 'Retrieve' aligns. The description adds that the tool returns connection details and schema, which is more about output content than behavioral traits. No additional side effects, permissions, or rate limits are disclosed, so the value beyond annotations is limited.

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?

A single sentence with no redundancy. The verb, resource, and use case are packed efficiently; every phrase 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 one-parameter getter with full schema documentation and an output schema, the description is complete. It clearly states what the tool retrieves and when to use it, making selection and invocation straightforward.

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 coverage, the only parameter database_id is already fully described as 'The ID of the database to retrieve' in the schema. The tool description adds only the modifier 'specific,' which does not significantly enhance parameter understanding, so the baseline of 3 is appropriate.

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

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

The description uses 'Retrieve' to clearly indicate a read operation, specifies 'specific Metabase database' to distinguish it from list_databases, and lists expected content ('connection details and schema'), making the purpose unambiguous and distinct from sibling tools.

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 'use this to examine database properties or troubleshoot connections,' providing concrete when-to-use guidance. However, it does not mention alternative tools or exclusionary scenarios, so it lacks full when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds context about returning field metadata and its purpose, but does not disclose additional behavioral traits such as authentication requirements or rate limits. With annotations present, this is adequate but not rich.

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 a single, well-structured sentence that front-loads the action and resource, then adds a relevant use case. No unnecessary words or redundant information.

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

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

Given the tool's simplicity (2 params, read-only annotation, output schema present), the description covers purpose and usage context adequately. It doesn't explain return details because the output schema handles that. Could mention exclusion criteria but not necessary for this basic lookup 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% for both parameters. The description echoes 'by table and column name' which matches the schema but adds no new technical detail beyond what the schema already provides. 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?

Description clearly states 'Look up a field's ID and metadata by table and column name' with a specific verb and resource. The use-case phrase 'essential for building parameter mappings' further distinguishes it from sibling tools like get_table or get_table_data.

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

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

Provides clear contextual use case: 'essential for building parameter mappings' and 'needed for filter connections'. However, it does not explicitly mention when not to use the tool or name alternative tools, so it stops short of full guidance.

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

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

The readOnlyHint annotation already covers safety, and the description adds context by explaining that the tool generates a link, not direct results, and that it enables interactive exploration. This goes beyond the annotation and clarifies the tool's side-effect-free nature, though it doesn't discuss potential link properties (e.g., expiry or auth).

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 a single sentence that conveys the core function and use case efficiently. The clause 'allows users to see results and experiment with data' is slightly redundant given 'interactive query exploration', but overall it is concise and front-loaded with the key verb 'Generate'.

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 link-generating tool with an output schema present and 100% parameter documentation, the description sufficiently covers the main context: generating a playground link for interactive exploration. It lacks minor details like whether the link is shareable or ephemeral, but these are not critical for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers both parameters with descriptions (query: 'The SQL query to execute in the playground', display: 'Display type (table, bar, line, etc.)'), and the description adds no additional parameter semantics. Since schema coverage is 100%, a score of 3 is appropriate.

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

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

This description clearly states the tool's function: generating a Metabase playground link. The phrase 'for interactive query exploration' specifies the purpose and differentiates it from siblings like execute_query or get_table_data, which return data rather than a link.

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

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

The description implies usage context: 'interactive query exploration' and 'user-friendly interface' suggest this is for users who want to see and experiment with results rather than just get raw data. However, it does not explicitly mention when not to use it or name an alternative, so it stops short of full guidance.

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

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

Annotations already declare readOnlyHint=true, and the description aligns with this. The description adds behavioral context by specifying the scope of returned information (schema, fields, metadata) and the intended use cases, which goes beyond the bare read-only annotation. No contradictions found.

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 a single sentence, front-loaded with the verb and object, and every phrase earns its place. It avoids redundancies and is immediately scannable.

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 tool is a read-only metadata retrieval operation with an output schema present. The description covers purpose and usage, and the structured fields fully cover parameters and return shape. Given the moderate complexity, no critical information is missing.

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 documents all four parameters (table_id, include_hidden_fields, etc.). The description does not add additional parameter-level detail, so it meets the baseline but does not exceed it.

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

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

The description uses the specific verb 'Retrieve' with the resource 'comprehensive table information' and elaborates with 'schema, fields, and metadata'. This clearly distinguishes it from sibling tools like get_table_data (data rows) and list_tables (table list), making the purpose unambiguous.

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

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

The description explicitly states 'use this to understand structure, explore fields, or get configuration details', providing clear usage contexts. It stops short of explicitly naming alternatives or stating 'when not to use', but the context strongly implies that data retrieval should use a different tool.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. Description adds 'sample data' and 'preview' behavior, indicating limited/first rows rather than full table, which goes beyond the annotation. It doesn't detail default limit specifics, but the schema covers that.

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 with clear front-loaded action, no filler, effectively communicates purpose and use cases.

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

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

For a simple read-only preview tool, the description combined with schema and output schema provides sufficient context. It covers purpose, use cases, and parameters, though it could mention alternatives for completeness, but not necessary.

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 covers 100% of parameter descriptions (table_id, limit with default). The description adds no new parameter semantics, only general usage context, so baseline 3 applies.

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

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

The description clearly states the tool retrieves sample data from a table for preview and analysis, with a specific verb and resource. It implicitly distinguishes from siblings by emphasizing 'sample data' for examination, though it doesn't explicitly name alternatives.

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?

Description provides clear use cases: 'preview and analysis,' 'examine content, verify quality, or understand data patterns.' It implies when to use this tool for exploratory reads but doesn't explicitly exclude alternatives like execute_query for more complex queries.

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 agent knows it's a safe read operation. The description adds context about filtering by source and model relationships but does not disclose potential pagination, result limits, or return format. With annotations covering the safety profile, this is acceptable but not rich.

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 a single, dense sentence with no fluff. It front-loads the main action ('Retrieve all Metabase cards') and the trailing clause provides valuable usage guidance without redundancy. Every word 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?

With an output schema and read-only annotation present, the description adequately covers purpose, filtering options, and typical use cases. It could mention pagination or the shape of the returned list, but for a discovery tool this is a minor gap. Overall, it's sufficient for an agent 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 description coverage is 100% for both parameters, so the baseline is 3. The description mentions 'models' as a source example and 'model relationships', but this adds little beyond the schema's own parameter descriptions. It does not provide additional format or behavior 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 'Retrieve all Metabase cards' with a specific verb and resource, and distinguishes itself from sibling tools like get_card by framing this as a discovery/overview tool with optional filtering. It leaves no doubt about what the tool does.

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

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

The description explicitly lists use cases: 'discover available cards, find specific cards by type, or get an overview of all analytical content'. It doesn't explicitly name alternatives to avoid, but the context is clear enough for an agent to know when to use this listing tool versus a single-card 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?

With readOnlyHint=true already declared, the description adds little behavioral detail beyond scope (all collections). It doesn't mention pagination, ordering, or other runtime behaviors, but the annotation covers safety. This is consistent with the high-calibration example where annotations lower the bar.

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 a single, well-structured sentence with the key action ('Retrieve all Metabase collections') front-loaded. It conveys purpose and usage without 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 list tool with one optional parameter and an output schema, the description provides sufficient context. Combined with the schema's parameter description and the readOnlyHint annotation, an agent has everything needed 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 coverage is 100% because the only parameter 'archived' is fully described in the schema. The description adds no additional parameter information, so the baseline of 3 applies.

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

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

The description clearly states the tool's purpose: 'Retrieve all Metabase collections for organizing analytical content.' It uses a specific verb and resource, and distinguishes itself from sibling tools by emphasizing 'all' collections, which separates it from tools like search_content or get_collection_items.

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 tells the agent when to use this tool: 'use this to understand content structure, find collections, or explore organizational hierarchy.' It provides clear context but doesn't explicitly mention alternatives or when not to use it, which prevents a 5.

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

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

The description aligns with the readOnlyHint annotation via the verb 'Retrieve'. It adds no additional behavioral details such as pagination, ordering, or limiting, and with an output schema present, the return structure is already defined. The added value beyond annotations is minimal.

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 a single, front-loaded sentence that states the primary action clearly and then lists use cases. No filler or redundant words beyond the slight overlap between 'Retrieve all dashboards' and 'discover available dashboards'.

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 zero-parameter read-only list endpoint with an output schema, the description fully covers the purpose and gives practical usage scenarios. There is no missing critical information such as required inputs or side effects.

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 no parameters, and the schema coverage is effectively 100% (empty schema). There are no parameter semantics to explain, so the baseline for zero-parameter tools applies (4). The description correctly omits 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 begins with 'Retrieve all Metabase dashboards', a specific verb and resource. The word 'all' clearly distinguishes this from sibling tools like get_dashboard (single dashboard) or get_card_dashboards (dashboards related to a card).

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

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

It provides clear usage context: 'use this to discover available dashboards, get an overview of analytical content, or find specific dashboards'. It does not explicitly mention alternatives or when not to use it, but the context is sufficient for a simple list 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?

The annotation readOnlyHint=true already communicates that this is a safe read operation. The description adds context like 'check connection status' and 'get an overview,' but doesn't disclose additional behavioral details such as pagination, response size, or any rate limits. This is acceptable for a simple list tool but not exceptional.

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 the primary action front-loaded. The first sentence says exactly what it does, and the second sentence adds practical use cases without redundancy. Every word 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?

For a parameterless read-only list tool with an output schema available, the description is sufficiently complete. It states the scope (all database connections), the purpose (discovery, status, overview), and no further context is needed for an agent to use it 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?

The tool has zero parameters, so the schema needs no explanation. The description's word 'all' confirms that no filtering is possible, which aligns perfectly with the empty input schema. This meets the baseline for parameterless tools.

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 all database connections in Metabase, using the specific verb 'Retrieve' and naming the resource. It distinguishes itself from siblings like get_database (single database) and list_tables (tables within a database) by explicitly covering all connections.

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 use cases: discover available data sources, check connection status, or get an overview. While it doesn't explicitly mention when not to use it or compare to alternatives, the context is strong enough for typical selection.

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 annotation readOnlyHint=true already establishes the tool is safe/read-only, so the description doesn't need to repeat that. It adds value by noting the tool retrieves 'all' tables unless filtered by IDs, providing scope and optional filtering behavior. 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 a single, well-structured sentence that front-loads the main action and includes useful use cases. There is no redundancy or filler.

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 (one optional parameter, output schema present, read-only annotation), the description provides sufficient context for an agent to understand purpose and behavior. The output schema covers return values, so no further explanation is needed. It is complete for a listing 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 schema covers the sole parameter (ids) with a clear description: 'Optional list of table IDs to filter by'. The tool description reiterates 'optional ID filtering' but adds no extra semantics beyond the schema. With 100% schema coverage, 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 'Retrieve all Metabase tables' with a specific verb+resource, and distinguishes it from siblings like 'get_table' and 'list_databases'. It also explains use cases: 'discover available tables, explore database schema, or get metadata about specific 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 provides clear context for when to use the tool ('discover available tables, explore database schema, or get metadata about specific tables'), but it does not explicitly mention alternatives or when not to use it. With sibling tools like 'get_table' and 'list_databases', a brief exclusion would make it a 5.

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

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

The annotation readOnlyHint=true already establishes the tool is a safe read operation. The description adds no further behavioral context such as result ordering, default filtering (e.g., archived excluded), or matching behavior. It merely restates the search scope, which is more about purpose than behavioral disclosure.

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 a single, front-loaded sentence that immediately conveys the tool's purpose and scope. It avoids redundant phrasing and earns every word, making it easy to parse while selecting the 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?

With six parameters but full schema coverage and an output schema, the description only needs to cover selection context. It does so adequately by explaining the cross-content search scope and intended use cases. Minor gaps exist (e.g., no mention of default archived behavior), but the schema and annotations cover most operational details, making it sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers 100% of parameters with descriptions, so the baseline is 3. The tool description does not add any parameter-specific semantics beyond what the schema already provides, so it neither improves nor worsens the situation.

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 across all Metabase content with specific resource types enumerated (cards, dashboards, collections, models). It uses a specific verb 'search' and distinguishes from sibling tools like list_cards or list_dashboards by emphasizing cross-content discovery.

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 context on when to use the tool ('find specific content, discover assets, or explore analytical resources'). It implies a search-oriented alternative to listing tools, but does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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