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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the error behavior (raises a tool error naming known entities) and lists the return contents, which implies it is a read-only operation. It does not explicitly state that it has no side effects, but the 'describe' verb and return of metadata suggest a non-mutating operation. The error message detail is a positive addition.

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 compact and well-structured. It leads with the core purpose, then lays out args and returns in a clear format, and ends with error behavior. Every sentence adds value; there is no fluff or repetition. The structure makes it easy for an agent to parse quickly.

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 is complete for an entity-description tool. It lists all return components, explains the error behavior, and gives a concrete example. An output schema exists, so detailed return types are not required in the description. Nothing critical is missing for the agent to successfully invoke the 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 0%, so the description must fully explain the 'name' parameter. It does: 'entity name, as returned by list_entities, e.g. "invoices"' — this specifies the value's source, format, and an example. The description adds meaning far beyond the bare schema (which only says 'string'), fully compensating for the lack of schema documentation.

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: 'Describe one entity in full detail' and enumerates exactly what is returned (description, synonyms, source table, primary key, dimensions, facts, filters). This distinguishes it from sibling tools like list_entities (which lists entities) and describe_metric (which describes metrics), making its scope obvious.

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 implicitly guides usage by specifying that the name should be 'as returned by list_entities', which tells the agent to first list entities to obtain a valid name. It also explains the error behavior for invalid names, which helps the agent handle failure modes. However, it does not explicitly state when to prefer this tool over describe_metric or other siblings, though the resource type (entity vs metric) makes this clear enough.

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 no annotations provided, the description carries the full burden and does a good job: it warns that grouping by non_additive_over dimensions would produce misleading results, and it discloses the error behavior (raises a tool error naming known metrics if name does not exist). It does not explicitly say the operation is read-only, but 'describe' strongly implies it and no side effects are mentioned. This exceeds the baseline for a tool with zero 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 compact, front-loaded with the core purpose, and every sentence earns its place: the purpose, the parameter guidance, the return enumeration, the non_additive_over warning, and the error behavior. No fluff or repetition.

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 low complexity (one parameter), the presence of an output schema, and no annotations, the description is remarkably complete. It covers what the tool returns, where valid parameters come from, cross-references query_metric, discloses a subtle semantic trap (non_additive_over), and describes error handling. An agent can call this correctly without any further 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?

Schema coverage is 0% and there is a single parameter, but the description adds exactly the needed semantics: name is 'metric name, as returned by list_metrics, e.g. "revenue"', plus the error case. It wisely avoids a static enum because metric names are dynamic, and instead tells the agent where to get valid values. This is a model of parameter explanation for an open-ended string.

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 a specific verb+resource statement: 'Describe one metric in full detail.' It then enumerates the exact fields returned (SQL expression, filters, owner, synonyms, time dimension, non_additive_over, allowed_dimensions), which distinguishes it clearly from sibling tools like list_metrics (lists all metrics) and query_metric (queries data), not just from describe_entity.

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 practical usage guidance: the name parameter must come 'as returned by list_metrics', and allowed_dimensions are explicitly said to be 'safe to pass to query_metric's by'. This contextualizes the tool in an agent workflow. It does not explicitly state when to prefer this over describe_entity, but the metric-vs-entity distinction is self-evident from the name and opening sentence.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It does well by detailing the return behavior: it returns the chosen path as a sequence of hops, and in cases where no single path is preferred, it returns null with an 'ambiguous: true' flag and a note, as well as listing every alternative path and the reason it was not chosen. This gives the agent a clear expectation of outcomes. It does not explicitly state that the tool is read-only, but the verb 'explain' and the nature of the task make that implicit. It also does not mention any side effects, which is appropriate for a query-style tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections for args and returns, and it is not overly verbose. It front-loads the main purpose in the first sentence. The inclusion of examples and the detailed return behavior is valuable, though it could be slightly trimmed without losing meaning. Overall, it is efficient and earns each sentence's 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?

The tool has an output schema, so the return structure is partially defined. The description adds key context beyond that: the meaning of 'ambiguous' and the fact that alternatives are also returned with reasons for non-selection. It does not mention that entity names must correspond to known entities (e.g., from list_entities), but this is derivable from the example and the nature of the tool. Given the moderate complexity (2 params, no nested objects), the description covers what an agent needs to invoke and interpret 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?

Because schema description coverage is 0%, the description must clarify the parameters, and it does so excellently. It defines 'from_entity' as the starting entity name with a concrete example ('invoices') and 'to_entity' as the destination entity name with an example ('customers'). This goes beyond the bare schema by providing real-world usage examples, making it clear what values are expected and how they are used.

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: to explain the preferred join path between two entities in words, including what it avoided. It names the resource (join path) and the specific verb (explain), and it distinguishes itself from sibling tools like query_metric or describe_entity by focusing on the join path explanation rather than data retrieval or entity metadata. The scope is precise 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 implies usage when one needs to understand how two entities relate, but it does not explicitly state when to use this tool versus alternatives. There is no 'use this when...' or 'instead of...' guidance. However, since no sibling tool is directly comparable (list_entities, describe_entity, etc. serve different purposes), the context is clear by implication. It lacks explicit exclusions or alternative routing.

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 no annotations, the description carries the behavioral disclosure burden. It indicates a read-only listing operation and specifies the returned contents, but does not mention pagination, ordering, or behavior for entities without descriptions or synonyms. Auth requirements and potential rate limits are also omitted.

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, efficient sentence that leads with the primary action and resource. It contains no filler or redundant information, making it easy to scan and understand.

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 is complete for a parameterless list tool with an output schema provided. It clearly states the return contents and scope; the output schema handles detailed return structure, so no further explanation is 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?

There are no parameters, so the description does not need to explain parameter meanings. The input schema is empty and fully covered, and the description adds context about the output contents, which is sufficient for a parameterless tool.

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 (list), the resource (entities/tables), the scope (semantic model), and the included fields (description and synonyms). It differentiates from list_metrics by specifying the resource type, making the tool's purpose immediately identifiable.

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 explains what the tool does but provides no explicit guidance on when to use it versus siblings like describe_entity or search_semantics. The use case is implied by the name and description, but no alternatives or exclusions are mentioned.

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 no annotations, the description must carry behavioral context; it does indicate a read-only enumeration of all certified metrics, but it does not disclose pagination, volume, filtering semantics, or what 'certified' means. This is adequate for a simple list operation but leaves some behavioral details unstated.

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?

One compact sentence with the action front-loaded and the returned fields listed concisely. There is no filler 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?

For a zero-parameter tool with an output schema, the description is largely complete: it states the scope and returned fields. It could briefly clarify when to use a sibling tool or define 'certified', but nothing essential for invoking the tool 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?

The tool has zero parameters, so there is no parameter ambiguity to document. The baseline of 4 applies because no parameter semantics are needed.

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 ('List') with a clear resource ('every certified metric') and enumerates the returned fields ('description, owner, and synonyms'). This distinguishes it from siblings like describe_metric (singular) and list_entities (different resource).

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 wording implies this is the tool for obtaining the full catalog of certified metrics, but it does not explicitly state when to prefer alternatives such as describe_metric or query_metric. There are no exclusions or when-not-to-use notes, so guidance is only implicit.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It does well by stating what the tool returns (columns, rows, exact SQL) and explicitly enumerating error conditions: unknown dimensions, ambiguous/unreachable joins, and non-additive dimensions. It could add an explicit read-only/no-mutation statement, but for a query tool the return and error behavior is well covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and then organized into Args, Returns, and Raises sections. Each sentence adds functional value: parameter formats, examples, default behavior, and error semantics. There is no filler 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?

For a 4-parameter tool with an output schema and no annotations, the description is complete. It explains all input formats, the return shape, default limit, and failure modes, and even relates to sibling describe_metric for what dimensions are safe. Nothing essential for calling the tool correctly 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 0%, so the description must compensate for the bare input schema. It does: metric is exemplified, by is given with entity.field format and a concrete example plus a pointer to describe_metric, where is given with entity.field op value format and an example, and limit is documented with its default. Every parameter receives meaning 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 opens with a specific verb and resource: 'Compile a metric query and run it against the model's DuckDB warehouse.' It clearly identifies the tool as executing metric queries, which distinguishes it from sibling tools that list or describe entities/metrics or explain joins.

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 context for when to use the tool: to query a metric with grouping and filtering. It also points the caller to describe_metric for allowed_dimensions, which serves as indirect guidance on using a sibling tool for safe inputs. It stops short of explicitly stating when not to use query_metric or naming alternatives for other scenarios.

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?

There are no annotations, so the description carries the behavioral disclosure burden. It does this well by stating case-insensitive substring matching, returning every match, and tagging each result with kind and owning entity. It does not mention empty-result behavior or result limits, but the core behavior is transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sections with no filler: purpose, Args, and Returns. Every sentence earns its place, and the most important information is 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 one-parameter search tool with an output schema, this covers the input semantics, matching behavior, return structure, and the reason the return shape matters. No crucial invocation detail 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 0%, but the description fully compensates. It defines the sole parameter 'text' as a free-text search with examples and matching semantics, adding meaning the schema alone lacks.

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 opens with a specific verb ('Search') and enumerates the full scope: entity, dimension, time dimension, fact, filter, and metric names, descriptions, and synonyms. This distinguishes it from siblings like list_entities and describe_metric, which target a single resource type.

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 context: use this for free-text, case-insensitive substring lookup across semantic objects, and it explicitly frames why it matters (disambiguating terms like 'region' before guessing). It does not explicitly name sibling 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.

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

No annotations are provided, so the description carries the full behavioral burden. The verb 'List' conveys a read-only, non-destructive operation, and the description discloses what the output contains (question, metric, dimensions, gold SQL) and the purpose (regression tests). It does not discuss edge behaviors like staleness or refresh behavior, but for a zero-parameter list tool this is a minor gap.

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 tight sentences with no filler. The first sentence front-loads the action and content, and the second adds the key interpretive fact (regression tests) that differentiates it from sibling tools. 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?

For a zero-parameter list tool with an output schema present, the description is complete: it tells the agent what is returned (verified questions with metric, dimensions, gold SQL) and why the list exists (the model's regression tests). Nothing an agent needs to invoke it correctly 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?

The tool has zero parameters and 100% schema coverage of an empty schema, so there is nothing for the description to add about parameters. Baseline 4 applies because there are no parameters whose meaning could be under-specified.

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 ('List'), names the resource ('this model's verified questions'), and specifies the contents ('known-good question, metric, dimensions, and the gold SQL'). It also distinguishes itself from the sibling catalog tools by labeling these as 'the model's own regression tests,' so an agent can tell it apart from list_entities and list_metrics without opening schemas.

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 supplies clear context for when this tool is relevant—when one wants to inspect the model's regression/test questions rather than the data catalog—via 'These are the model's own regression tests.' It does not explicitly name alternatives or state when not to use it, but the contrast with siblings (list_entities, list_metrics, describe_*) is reasonably implied by describing the resource as the model's own tests.

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