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

With no annotations provided, the description carries the burden of behavioral disclosure. It does disclose that the tool executes DDL statements and creates tables and foreign key constraints. However, it omits the destructive potential of the dropExisting parameter (dropping existing tables), as well as any permissions or transactional side effects, leaving a meaningful gap for a mutation 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 two sentences with no filler, and the core action is front-loaded. Every word earns its place, making 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 covers the core purpose and side effect of creating tables and constraints, but for a mutation tool with no annotations and no output schema, it lacks important contextual details such as the destructive behavior of dropExisting, what a successful call returns, and whether the operation is transactional. It is adequate for basic invocation but not fully 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?

Schema description coverage is 100%, so the schema already documents both parameters fully. The description adds no parameter-level semantics beyond what the input schema provides, which places it at the baseline of 3.

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 states a specific verb and resource: 'Create PostgreSQL tables from the ER diagram.' It further clarifies the mechanism ('execute DDL statements to create tables and foreign key constraints'), which clearly differentiates it from sibling tools like generate_sql (which generates SQL without executing) and drop_schema (which removes schema).

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 the tool should be used when you want to create tables from an ER diagram, but it does not explicitly state when to use it versus siblings, nor does it mention any exclusions or alternatives. The context is implied rather than stated.

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 full burden of behavioral disclosure. It clearly and prominently warns that executing this tool 'will delete all data', which is the most critical behavioral trait. It does not explicitly say the operation is irreversible or that confirm=true is required, but the schema already documents the confirm parameter.

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 only two sentences, front-loads the action, and includes a high-value warning. Every part contributes useful information; 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 simple two-parameter destructive tool with full schema coverage, the description is complete enough for an agent to understand what will happen and to invoke the tool safely. The schema provides the remaining confirmation details, and no output schema 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?

Schema description coverage is 100%, with both confirm and diagram already described in the input schema. The description adds no new parameter-level meaning, which is acceptable given the schema already fully documents each parameter.

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 states a specific action and resource ('Drop all tables defined in the ER diagram') and is clearly distinguishable from siblings like create_schema, list_entities, and validate_diagram. The destructive purpose is 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 destructive warning strongly implies when it should be considered, but the description does not explicitly state when to use it versus alternatives or when not to use it. There is no mention of safer alternatives for partial or non-destructive operations.

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 burden of disclosing behavior. It clearly states that SQL is generated 'without executing them,' which is the key non-destructive behavioral trait. It could add more detail about reliance on a configured source or error behavior, but the core transparency is present.

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 core action and the critical non-execution caveat are front-loaded, followed by a brief use-case clause. 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 single-optional-parameter tool with no output schema, the description is mostly complete: it names the input source, the output (SQL DDL statements), and the non-execution behavior. It does not elaborate on return shape or edge cases, but the low complexity and schema coverage make it sufficient.

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 parameter description already explains both the 'diagram' input and the fallback to a configured source. The tool description adds no new parameter-level meaning beyond echoing 'from the ER diagram,' 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 states a specific verb ('Generate'), a specific resource ('SQL DDL statements'), and a clear source ('from the ER diagram'). It also explicitly distinguishes itself by noting 'without executing them,' which sets it apart from sibling execution tools like create_schema.

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 'Useful for reviewing the SQL before creating tables' gives clear context for when to use the tool. It implies an exclusion of execution, but does not explicitly name an alternative such as create_schema, so it stops short of full when/when-not 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?

With no annotations, the description carries the full burden of disclosing behavioral traits. 'Get information' weakly implies a read-only operation, but it does not state that the call has no side effects, whether the server must be running, what happens if it is not, or what the response contains.

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 concise sentence with no filler. It front-loads the main action and resource while staying short 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?

Given the tool's simplicity (zero parameters), this is minimally adequate. However, with no output schema and no annotations, the vague term 'information' leaves the return value undefined; an agent cannot know whether it will receive a list of endpoint paths, HTTP methods, server status, or something else.

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 description does not need to clarify parameter meaning. The baseline for no parameters is 4, and no parameter-related information is missing.

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 ('Get') and names a concrete resource ('the running API server and its endpoints'), making the tool's purpose clear. It is distinguishable from siblings like start_api_server and stop_api_server, though it does not explicitly differentiate itself from test_connection.

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

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

No guidance is provided about when to use this tool versus siblings. The phrase 'running API server' implies the server should be started first, but it does not state this condition or mention alternatives such as test_connection for connectivity checks.

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 must disclose behavior on its own. It only says 'Get', which suggests a read-only operation, but it does not mention that the entity is resolved from a Mermaid diagram, how the optional diagram parameter affects execution, or what happens if the entity is not 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 17-word sentence with no filler. The main verb and object are front-loaded, and every word contributes to the purpose.

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 gives a reasonable summary of the return content in the absence of an output schema, and the input schema covers the diagram parameter. However, the description does not explain that the entity comes from a diagram or specify not-found behavior, so it is not fully 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?

Schema coverage is 100%, so both parameters are already documented. The description adds a little meaning by clarifying that entityName refers to the specific entity and that details include attributes, types, and keys, but it adds nothing about the diagram parameter beyond what the schema provides.

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

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

The description clearly states the verb 'Get' and the resource, 'detailed information about a specific entity', and explicitly lists what is included (attributes, types, keys). This distinguishes the tool from siblings like list_entities (which lists all entities) and get_relationships (which focuses on relationships).

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 'specific entity' implies the tool is for a single entity lookup, but there is no explicit guidance on when to use this tool versus alternatives such as list_entities or get_relationships. The usage context is only implied, not stated.

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 implies a read-only operation ('Get') but does not state what happens when the diagram parameter is omitted, whether the operation is safe, or what error conditions might arise. The behavior around the configured diagram source is entirely hidden.

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, compact sentence that immediately states the operation, target, and a key output detail. There is no waste 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?

There is no output schema, and the description only mentions cardinality without describing the return structure, pagination, or behavior when no relationships exist. Given the tool's moderate complexity and absence of annotations, the definition leaves too much for the agent to discover at runtime.

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 both parameters already have adequate structured documentation. The description adds the 'cardinality information' return context but does not clarify the relationship between the diagram and entityName parameters or the fallback behavior of diagram. Baseline 3 is appropriate since the schema does the heavy lifting.

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 'Get' with a clear resource: relationships between entities in the ER diagram, and adds the distinguishing feature 'cardinality information.' This differentiates it from sibling tools like list_entities and get_entity_details, which target entities or entity details rather than relationships.

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

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

No guidance is given about when to use this tool versus alternatives such as list_entities or get_entity_details. There is no mention of prerequisites, exclusions, or the optional diagram source fallback, so an agent must infer usage from the name and the schema.

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 burden of behavioral disclosure. It only says 'list' — it does not address whether the operation is read-only, what happens when no diagram is provided (beyond what the schema already says), potential failure modes, or 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 clean, front-loaded sentence with no redundant words. It is efficiently structured, though brief to the point of omitting useful context.

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?

Adequate for a simple listing tool with one optional parameter, but with no output schema and no sibling differentiation, an agent is left guessing about the return shape and about how this overlaps with parse_er_diagram. Complete enough to attempt a call, not complete enough to call confidently.

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 the single diagram parameter at 100%, including the fallback to a configured diagram source, so the schema does the heavy lifting. The description adds no parameter-level details beyond the general purpose, which merits the baseline 3.

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 (List), resource (entities/tables in the ER diagram), and the returned fields (names and aliases). It clearly describes what the tool does, though it does not distinguish itself from sibling tools like parse_er_diagram or get_entity_details, so it stops short of a 5.

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

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

No guidance on when to use this tool versus alternatives. An agent cannot tell whether to call this instead of parse_er_diagram for obtaining an entity list, and no conditions or exclusions are given.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It states the parse/extract action but does not reveal whether the extracted schema is persisted, whether it overwrites an existing schema, whether a connection must be active, or what the actual return value is. For a tool sitting among schema-management siblings, this is a meaningful transparency 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?

The description is a single direct sentence with the action and output front-loaded and no filler. It earns a 4 for efficiency, though it stops short of 5 because the terseness omits usage and behavioral context that would make it genuinely more useful.

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 no annotations and no output schema, the description needs to explain what happens on invocation and what the caller receives. It names the extracted components (entities, attributes, relationships) but omits side effects, persistence behavior, return format, and how this relates to sibling tools. This is insufficient for an agent deciding between parse_er_diagram, validate_diagram, and list_entities.

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

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

The input schema has 100% coverage for the single optional 'diagram' parameter, including the fallback to the configured diagram source. The tool description adds no parameter-level detail beyond the 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 names a specific action ('Parse'), a specific input type ('Mermaid ER diagram'), and a concrete outcome ('extract the complete database schema including entities, attributes, and relationships'). This clearly distinguishes it from sibling tools that list, validate, or generate rather than parse and extract.

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 the tool is the entry point for loading a schema from a diagram, but it gives no explicit guidance about when to prefer it over validate_diagram, list_entities, or generate_sql. There is no mention of prerequisites, ordering, or exclusions, so the agent must infer usage 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Start' without revealing side effects such as whether the server runs in the background, blocks the process, binds a port, requires auth, is idempotent, or how to stop it. This is a significant gap for an action that likely starts a long-running process.

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 direct sentence with a clear verb, object, and domain. No filler or redundant phrasing; the key 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?

The description is adequate for a simple one-parameter start command, but it misses lifecycle and side-effect information. With no output schema, an agent does not know what a successful invocation returns, whether the server is long-running, or how to confirm it is ready—so the definition is acceptable but not 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?

Schema description coverage is 100% for the single 'diagram' parameter, so the baseline is 3. The tool description adds a little domain context by tying the server to the ER diagram entities, but it does not meaningfully clarify parameter format, defaults, or the fallback to configured source—that is already covered by the schema.

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

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

The description clearly identifies the action ('Start'), the resource ('REST/GraphQL API server'), and the scope ('for the entities in the ER diagram'). This distinguishes it from sibling tools like stop_api_server and get_api_endpoints without needing to inspect their 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 implies when to use the tool—after working with an ER diagram and before interacting with API endpoints—but it does not explicitly state when not to use it or mention alternatives. It also does not reference the natural counterpart stop_api_server, leaving some usage context 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Stop the running API server' and does not disclose consequences such as whether data is lost, whether the action is reversible, whether it is idempotent, or what happens if no server is running. This is a meaningful gap for an imperative lifecycle action.

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, complete sentence that is front-loaded and contains no fluff. Every word earns its place, and it is appropriately sized for a tool with no parameters.

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 simple and has no parameters, but the description is still minimal. It omits what happens on success or failure, whether a running server is required, and how this relates to start_api_server or get_api_endpoints. For a lifecycle operation, these gaps prevent the description from being fully complete, though the basic action is clear.

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 the schema coverage is 100%, so there is nothing for the description to add about parameter syntax. The baseline for a zero-parameter tool is 4, and the description adequately aligns with the empty 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 uses a specific verb ('Stop') and a clear resource ('the running API server'), so an agent understands the action. It does not explicitly distinguish itself from the sibling tool 'start_api_server', but the inverse relationship is self-evident from the names and description.

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 no guidance on when to use this tool or how it relates to alternatives. There is no mention of preconditions (e.g., server must be running) or exclusions, and no reference to the obvious sibling 'start_api_server'. The agent is left to infer when this tool is appropriate.

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 disclosing behavior. It does state that the tool returns 'success or error message,' which is a useful behavioral detail. However, it does not explicitly state that the operation is non-mutating or side-effect free, which is important for an agent to know when deciding whether to invoke it.

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 consists of exactly two short sentences, each earning its place: the first states the action and target, the second clarifies the output. It is front-loaded and free of any redundant or filler content.

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 no output schema and no annotations, the description is mostly adequate but leaves some gaps. The return value is described vaguely as 'success or error message' without specifying the exact structure, and the lack of side effects is not explicitly confirmed, which an agent may need to know for safe 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 is empty, so there are zero parameters to document. Per the calibration rule, a description for a tool with no parameters receives a baseline of 4 because there is no semantic gap to compensate for.

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 ('Test') and a clear resource ('the PostgreSQL database connection'), making the tool's purpose immediately obvious. It is naturally distinct from sibling tools like list_entities or generate_sql, which operate on entities and SQL rather than the connection itself.

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 no guidance on when to choose this tool over alternatives, nor does it mention any prerequisites or context that would trigger its use. An agent is left to infer that it should be used for connectivity checks, but there is no explicit when-to-use or 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?

With no annotations, the description carries full behavioral burden. It states the validation scope but does not disclose the return format, whether errors are thrown or returned as a collection, or what happens with invalid input. This leaves the agent uncertain about expected outcomes.

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, front-loaded sentence that communicates the tool's core action without any filler. Each word contributes meaning.

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 validation tool with no output schema and no annotations, the description should specify what the validation produces (e.g., boolean, error list, exception behavior). The current description omits this essential operational detail, so an agent cannot reliably anticipate the tool's response.

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 the diagram parameter. The description adds only the context that the parameter is the subject of validation, which is redundant, 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 states a specific verb ('Validate') and a specific resource ('a Mermaid ER diagram'), and specifies the exact concerns ('syntax errors and structural issues'). This unambiguously distinguishes it from sibling parse_er_diagram, which is about parsing rather than validating.

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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, recommended ordering (e.g., validate before parsing or generating SQL), or any exclusions.

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