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

Annotations already declare the tool read-only, idempotent, and non-destructive, so safety is covered. The description adds substantial value by detailing the return payload (columns, constraints, indexes, comments), which is especially important since no output schema exists.

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 filler. The first sentence front-loads the tool's core purpose and return details, and the second explains when to use it. Every clause 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 2 simple parameters, annotations covering safety, and a detailed description of the return contents, nothing essential is missing. The lack of an output schema is compensated by the explicit list of returned metadata.

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

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

Schema description coverage is 100%, and the schema already documents both parameters ('Table or view name, unqualified' and 'Schema name.'). The description does not add parameter-level meaning, but it doesn't need to; 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 uses a specific verb and resource ('Full description of one table') and enumerates the exact metadata returned (columns, types, nullability, defaults, keys, constraints, indexes, comments). It is clearly distinct from list_schemas/list_tables, but does not explicitly separate itself from table_relationships, even though foreign keys are included.

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 phrase 'This is the core tool once you know which table you want' gives clear contextual guidance: use it after table discovery, not for browsing schemas or tables. It does not name alternatives or state when-not-to-use, so it falls just short of explicit 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?

Annotations declare readOnly and idempotent, and the description adds the key behavioral nuance that analyze: true executes the statement and returns measured timings instead of estimates. This is useful context beyond the structured 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?

Three short sentences with no filler: primary behavior, parameter behavior, and usage guidance are each given one sentence in logical order.

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 two-parameter tool with rich annotations, the description says everything needed to select and use it: default plan-only behavior, analyze=true behavior, and the intended use case. No output schema is required; 'query plan' sufficiently describes the result.

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 schema already documents both parameters. The description adds value by explaining that analyze toggles between estimates and measured timings and reinforces that sql must be a SELECT or WITH statement.

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?

States a specific verb and resource: show the query plan for a SELECT, and clarifies that the default does not run it. The 'tune before running' phrasing differentiates it from running actual queries via siblings like run_select.

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?

Gives actionable usage context: use it to tune a query before running it against a large table. It does not explicitly name run_select as the alternative or state when not to use it, so it falls just 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?

Annotations already indicate this is a mutating but idempotent and non-destructive action; the description adds meaningful behavioral context by stating it writes only to the given path and produces a Markdown file. It does not explicitly address overwrite behavior or error conditions, but the annotations plus the explicit path boundary largely cover the typical concerns for a file-writing 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?

Three concise sentences, each earning its place: the first defines the action and output content, the second explains a practical benefit, and the third provides safety and sibling differentiation. It is front-loaded and free of 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 low parameter count, full schema coverage, and annotations covering the safety profile, this description is complete for correct invocation. An agent knows exactly what will be written, where it will be written, and that no other tool in this set performs writes. No output schema is needed for a write action, and no required 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?

Both parameters are fully described in the input schema (schema name and output_path with the .md requirement). The description reinforces these with 'one schema' and 'the path you give it,' but adds little semantic value beyond what the schema already provides, 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 opens with a specific verb and resource: 'Write a Markdown data dictionary for one schema to a file,' and enumerates exactly what the document includes (every table, column, type, nullability, key, constraint). It also distinguishes itself from siblings by stating 'This is the only tool here that writes anything,' so an agent can tell it apart from the read-only introspection tools at a glance.

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 useful context: it explains the benefit of using this tool ('Once written, you can read the schema from disk with no database connection') and explicitly notes it is the only sibling that writes, which frames when to pick this over the other read-only tools. It does not explicitly name alternative tools to use instead for specific cases, so it falls 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?

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds cross-schema scope and the 'every table that carries it in one call' behavior, but it does not mention limits, ordering, or result shape; this is useful but not rich 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?

Two tightly written sentences front-load the core capability, then add a targeted usage rationale with a concrete example. Every clause earns its place; there is no 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?

For a two-parameter search tool with safety annotations, the description is largely complete: it states scope, optional filter, and the intended efficiency benefit. There is no output schema and the exact return format is implied rather than stated, but an agent can infer it will see the matching columns and tables.

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

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

Schema description coverage is 100%, with clear definitions for name and the optional type substring. The description's 'optionally filtered by type' and customer_id example mirror the schema rather than adding new semantic meaning, so the 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 opens with a specific verb and resource: 'Search for columns by name across every schema, optionally filtered by type.' It clearly distinguishes the tool from sibling listing tools by emphasizing cross-schema column search rather than table or schema enumeration.

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 gives explicit guidance to use this instead of listing tables when the database is large, with a concrete customer_id example. It does not spell out exclusions relative to describe_table or table_relationships, so it stops short of a full when/when-not matrix.

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 communicate read-only, idempotent, non-destructive behavior. The description adds genuine output context—that results include per-schema table and view counts—which is useful.

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 the core operation front-loaded and the usage cue in the second sentence. No 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?

For a zero-parameter discovery/list tool, the description tells an agent what it will get (schemas with table and view counts) and when to call it. No output schema is present, but the description supplies the essential return shape.

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

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

No parameters exist, so the schema covers everything; per the rubric the baseline is a 4. The description doesn't need to add parameter-level detail.

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?

Verb 'List' plus direct object 'schemas in the database' makes the operation unambiguous. The added detail about table/view counts and the 'Start here' guidance distinguishes it from sibling table-level 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?

Explicitly positioned as the starting point when database shape is unknown, giving a clear precondition. It does not name alternatives or state when not to use it, so not a full 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?

Annotations already declare read-only/idempotent/non-destructive behavior, so the description adds beyond them by disclosing that row counts are planner estimates rather than exact numbers and that views are included. This is useful non-obvious 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?

Two compact sentences: the first states the core behavior and output, the second adds a use case and a critical caveat. No filler or redundant restating of the tool name.

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 listing tool with no output schema, the description conveys what is returned (tables and views, estimated row counts, on-disk size), the ordering, and the estimation caveat. Nothing essential is missing for correct invocation.

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 already fully describes the single 'schema' parameter with an example, and schema description coverage is 100%. The description adds no parameter-level detail beyond confirming the scope is one schema, 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 a specific verb ('List') with a concrete resource ('tables and views in one schema') and adds distinctive return details (ordering by size, estimated row count, on-disk size). This clearly separates it from siblings like list_schemas and describe_table.

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

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

It gives an explicit use case: 'Use this to find out what is expensive before you query it.' It does not explicitly state when not to use it or name alternatives, but the intended context is clear enough for an agent to select this 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 mark it read-only/idempotent/non-destructive, and the description adds meaningful runtime behavior: read-only transaction, statement timeout, result cap, and masking of secret-looking columns. It also names specific refused statement classes beyond the annotation's safety profile.

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

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

Three sentences pack accepted input, refusal classes, execution constraints, and output limits without fluff. A minor redundancy exists across 'no write mode,' readOnlyHint, and the refusal list, but overall the description remains tight and readable.

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 query tool, the description covers allowed statements, refusals, execution context, timeout, cap, and masking, so an agent can invoke it correctly. It does not describe return shape, but with no output schema and query-dependent results this is a minor 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 single sql parameter has 100% schema coverage, so the schema already documents 'a single SELECT or WITH statement. No trailing second statement.' The description reinforces the same constraint but does not materially add parameter-level 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+resource—'Run one SELECT or WITH statement'—and the title reinforces read-only. It clearly distinguishes run_select from the schema-discovery siblings by being the only arbitrary query tool.

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 clearly states what will be refused and that there is no write mode, so the agent knows when not to attempt DDL/DML. However, it never explicitly contrasts with sibling tools like list_tables or explain_query, leaving 'when to use this instead' to inference.

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 annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description need not restate safety. It adds substantive behavioral detail: secret-looking columns are masked, results are capped by both row count and size, and truncation is reported. This meaningfully exceeds the structured 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?

Three sentences with no fluff. The core action is front-loaded, and each subsequent sentence adds distinct value: masking behavior, cap behavior, and truncation notification. Nothing extraneous is present.

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 3-parameter tool with strong annotations, the description covers the important runtime behaviors: masking, cap limits, and truncation response. It could be slightly more explicit about the exact shape of the returned result (e.g., whether column names/types are included), but overall it is complete enough for correct invocation.

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

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

Schema description coverage is 100%, and the schema already documents limit (including default, min, and max), table, and schema. The description adds no parameter-level meaning beyond what the schema provides, 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 a specific verb and resource: 'Return the first few rows of a table'. This clearly distinguishes sampling data from sibling tools like describe_table (structure) and run_select (arbitrary queries), and the added 'shape of the data' purpose makes intent unmistakable.

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 'so you can see the shape of the data' clause gives a clear implied context, but the description never explicitly states when to use this tool versus alternatives like run_select or describe_table. There is no when-not guidance or named sibling fallback, so the agent has to infer selection criteria.

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 establish that this is read-only and idempotent. The description adds meaningful behavioral detail beyond that: it traverses foreign keys in both directions up to a depth, and defines what outbound versus inbound keys mean. This gives the agent a real sense of how results will be structured without needing the output schema.

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, purposeful sentences: the first states the core behavior, the second clarifies directional semantics, and the third gives practical guidance. There is no redundant text or repetition of the title.

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 read-only metadata traversal tool with three parameters and fully documented schema fields, the description is complete enough for an agent to decide when and how to call it. The only gap is that there is no output schema or example return shape, so an agent may be unsure exactly what the result payload looks like, though the description's directional explanation mitigates this.

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 input schema already documents schema, table, and depth well. The description reinforces the depth concept and directional behavior but does not add significant new parameter meaning beyond what the schema 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?

The description uses a specific verb, 'follow', and a precise resource, foreign keys, with direction and depth scoping. It clearly distinguishes this relationship-traversal tool from siblings like describe_table or find_columns by focusing on join discovery rather than table structure or column lookup.

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

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

The description explicitly says 'Use this to work out how to join instead of guessing from column names,' providing clear context for when the tool is appropriate. It gives a when-not condition but does not explicitly name alternative sibling tools, so it stops just short of a full alternative-routing explanation.

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