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

With no annotations, the description carries the full burden and is largely effective: it discloses the algorithm, the v5 shared-layout behavior, and explicitly excluded elements. Minor gap: it does not state whether changes are persisted or the operation is reversible.

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 dense sentences front-load the core action and then add a useful but slightly cryptic v5 note. All sentences contribute, though the version-specific wording could be clearer for new users.

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, the description covers main behavior and exclusions, but omits what the tool returns and whether it modifies the source in-place. Without an output schema, that missing confirmation leaves a 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?

Input schema coverage is 100% and already explains the source parameter variants thoroughly. The description adds nothing about the source parameter, matching the schema-only baseline.

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

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

Purpose is unambiguous: auto-arranges entities by relationships, explicitly naming the dagre-LR algorithm. It also distinguishes from siblings by stating what is not moved (reference copies, notes, waypoints).

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?

Usage is implied through the verb 'auto-arranges' but no explicit when/when-not is provided. The v5 note about the removed 'view' parameter is historical context, not usage guidance, and no alternative tool is referenced.

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 takes full responsibility for behavioral disclosure. It explains error vs warning semantics ('strict promotes to errors'), states read-only nature ('Read-only'), guarantees security ('database URL never leaves this process'), and notes plan/login requirements ('Pro plan required; requires login').

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

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

The description is concise (three sentences) and front-loaded with the core purpose. Each sentence adds value: purpose, error/warning behavior, and safety/prerequisites. 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 moderate complexity and lack of output schema, the description sufficiently covers what the tool checks and the error/warning behavior. It does not explicitly describe the return format, but the mention of errors and warnings implies its shape. Slight gap is that it doesn't mention output structure or examples, but this is not critical 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 coverage is 100%, and the descriptions in the schema already explain each parameter (url, schemaSql, dialect, source, etc.). The tool description echoes the url/schemaSql distinction and strict's effect, but adds no new 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 clearly states the tool's function: 'Checks whether a live database (url) or a schema dump (schemaSql) has drifted from the ERD's physical model.' It names a specific verb and resource, and the scope (errors vs warnings) distinguishes it from related tools like diff_erds or introspect_db.

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 (to check drift) but does not explicitly discuss alternatives or when not to use it. It mentions needing a login and Pro plan, which are prerequisites, but does not contrast with sibling tools like introspect_db or diff_erds. Guidance is implied but not explicit.

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 burden of behavioral disclosure. It mentions reading 'the latest workspace-standard master' and comparing to the generated name, but does not explicitly state that the operation is read-only, nor explain side effects, permissions, or response format details.

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, front-loads the primary purpose, and efficiently conveys conditional behavior without redundancy or wasted 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?

While the description covers the main modes, it omits output semantics (e.g., what 'providedMatches' actually returns), error conditions, and any side-effect caveats. With no output schema and no annotations, more detail is expected for full completeness.

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 low (33%), only 'source' is described in the schema. The description adds meaning to 'physicalName' (triggers comparison) and 'source' variants (workspaceId reads master), but 'logicalName' is not explained beyond the tool's overall purpose, leaving a gap.

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: 'Checks a logical name against the team naming standard (word list + rules).' It uses a specific verb ('Checks') and resource (logical name vs. naming standard), and the conditional modes distinguish it from related siblings like generate_physical_name.

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 different usage modes ('With physicalName', 'With a {workspaceId} source'), but does not explicitly mention alternatives or when not to use the tool. It gives useful situational guidance without exclusions.

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 disclose login requirements for server saves and workspaceId, and explains the local/file vs server distinction. However, it omits details such as whether an existing file gets overwritten, what response is returned, or the mutual exclusivity of sql/dbml (though schema covers that). The transparency is adequate but has clear gaps.

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

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

The description is three sentences, front-loaded with the core purpose and then efficiently covering the key behavioral variants. Every sentence adds useful information with no fluff or repetition, making it appropriately concise.

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

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

Considering the tool's complexity (6 parameters, nested target object, no output schema, no annotations), the description covers the main usage scenarios: source, target, workspace binding, and auth requirements. It does not explain the 'name' parameter or return details, but these are either self-evident or covered by schema. The description is sufficiently complete for an agent to understand the tool's primary behavior.

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 already provides descriptions for 5 of 6 parameters (name is only missing). The description adds meaningful semantics beyond the schema, especially for target (local file vs server) and workspaceId (binds to naming standard, requires login). It also clarifies the 'empty or from SQL/DBML' source options, which maps to sql/dbml. This adds value beyond structured fields.

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 'Creates a new ERD' and specifies the source options (empty, SQL, DBML) and target modes (file, server). However, it does not explicitly distinguish this from sibling tools like import_sql or import_dbml, which could also create ERDs from SQL/DBML, so it lacks full sibling differentiation.

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: for creating a new ERD, with explicit choices for local vs server save and workspace binding. It does not mention alternatives or exclusions (e.g., when import_sql/import_dbml would be more appropriate), but the core usage scenarios are well explained.

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 full responsibility for disclosing behavioral traits. It only states 'Deletes an attribute' without mentioning irreversibility, cascading effects, permissions required, or any side effects. For a delete operation, this is a significant 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 short sentence with no fluff, but it is under-specified rather than appropriately concise. It omits critical context that the agent needs, making it an example of under-specification rather than impactful brevity.

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 complexity (3 required parameters, including a nested source object) and no output schema, the description is deeply inadequate. It doesn't explain what happens upon deletion, whether attributes can be deleted from both local files and server ERDs, or any dependencies. The agent would be left guessing about the operation's 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?

Schema description coverage is only 33% (only 'source' has a description; entityId and attributeId are undocumented). The description 'Deletes an attribute' adds no parameter semantics, failing to clarify the roles of entityId and attributeId. There is no compensation for the schema gaps.

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 'Deletes an attribute' clearly states the verb and resource, making it easy to identify the tool's primary action. It differentiates from sibling tools like delete_entity and delete_relationship by specifying 'attribute'. However, it lacks any mention of the attribute's context (e.g., entity, ERD) that the schema requires, so it's not a full 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?

The description provides no guidance on when to use this tool versus alternatives like delete_entity or upsert_attribute. It neither states the intended use case nor mentions any alternatives or exclusions, leaving the agent to infer usage solely from the name.

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 burden of disclosing behavior. It does reveal a specific error condition (dictionary_is_linked for glossaryLink dictionaries), which is useful. But it does not describe other important behaviors such as irreversibility, permissions needed, or success response format, leaving gaps.

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 unnecessary words. The main action is front-loaded, and the rejection condition is stated concisely. 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?

The tool is simple and the description gives a key warning. However, there is no mention of how to obtain the entryId, what happens on success, or whether deletion is permanent. Given the absence of annotations and output schema, a bit more context would improve completeness.

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 documents 'source' with a description, but 'entryId' is just a string with no description. The tool description adds no explanation of entryId, so the parameter remains ambiguous. With 50% schema description coverage, the description should have compensated but did not.

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 ('Deletes') and the resource ('glossary entry'), which aligns with the tool name and distinguishes it from other delete tools like delete_entity and delete_attribute. It also provides a specific failure condition, 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 gives an explicit when-not condition: standard-linked (glossaryLink) dictionaries are rejected. This tells the user when the tool will not work. However, it does not mention alternative tools or broader use cases, so it falls short of 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses the important side effect that attributes referencing the domain are unlinked, which adds useful context. However, it omits other details like irreversibility, permission requirements, or what happens to the domain's own attributes, leaving some behavioral traits undisclosed.

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 and a critical side effect. Every word earns its place, making it appropriately concise and well-structured.

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

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

For a destructive operation with no annotations and no output schema, the description provides the core action and one side effect but lacks details on return values, error conditions, and permanence. It is adequate for a simple tool but not fully complete in context.

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 the 'source' parameter but leaves 'domainId' as a plain string with no description. The tool description does not add any explanation for 'domainId' or clarify how to obtain its value, so it fails to compensate for the 50% schema coverage gap.

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 'Deletes' and clearly identifies the resource as 'domain', making the action unambiguous. It also adds a key behavioral detail about unlinking attributes, which helps distinguish it from sibling delete tools for entities, attributes, and 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 description does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. However, the verb and resource name imply that it should be used to delete a domain, so usage is reasonably inferred.

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

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

The description discloses a key behavioral trait: deleting an entity also deletes its relationships. However, with no annotations and a destructive operation, it would be important to mention that deletion is permanent, whether it requires specific permissions, and what happens to other dependent data like attributes. The partial disclosure is useful but not comprehensive.

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 that communicates the essential action and scope without any filler. It is front-loaded and to the point, 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?

For a destructive tool with no annotations or output schema, the description is too sparse. It does not state what happens to attributes associated with the entity, whether deletion is irrevocable, if any prerequisites must be met, or what the success/failure response looks like. Given the tool's impact, the description leaves significant gaps in understanding for safe and 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 nicely describes the 'source' parameter with a detailed anyOf structure and explanation, but 'entityId' is left completely undocumented. The description adds no parameter-level meaning beyond what the schema already provides; it does not clarify what entityId refers to or how to format it. With only 50% schema coverage, the description should compensate for entityId but fails to do so.

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 action: 'Deletes an entity' and adds the important scope of 'including its relationships.' This effectively distinguishes it from sibling tools like delete_relationship, which targets only a relationship, and delete_attribute, which targets attributes.

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 explicit guidance on when to use this tool versus alternatives. It does not mention when to prefer deleting an entire entity over deleting only relationships, nor does it address situations where the tool should be avoided. The single sentence implies usage by its verb, but lacks the necessary context to fully guide an agent.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does mention the important cascade behavior of deleting derived FKs, which is a useful warning. However, it does not disclose irreversibility, permission requirements, error behavior, or what happens to dependent objects beyond the FKs.

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 with no wasted words. It is front-loaded with the verb 'Deletes' and the resource, and the parenthetical adds essential behavioral information 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?

Given the simplicity of the tool but lack of annotations and output schema, this description is too minimal. It does not explain what happens on success, how to find relationshipId, or typical usage scenarios. An agent may not know when to invoke it or what to expect.

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 only 50%; the source parameter is well-described but relationshipId has no schema description. The tool description adds no meaning for relationshipId or how to obtain it. With low coverage, the description should have compensated, but it does not.

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 'Deletes a relationship' with a specific verb and resource. The parenthetical '(including derived FKs)' distinguishes it from other relationship tools like upsert_relationship or list_relationships, 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 gives no guidance on when to use this tool versus alternatives such as delete_entity or list_relationships. It lacks prerequisites, context, or any explicit 'when to use' or 'when not to use' information.

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 transparency burden and does so thoroughly. It discloses that unchanged items are omitted, that text-parsed sides yield different IDs causing many added/removed entries, that import behavior is full-replace, and that summary aggregates only entities while arrays contain domain/relationship changes — all beyond the 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 sentences, each packed with distinct information: what is compared, when to use it, and how to read the output. No filler or redundancy; the most important action and scope appear first.

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?

Despite having no output schema, the description tells the agent what to expect from the result ('summary aggregates entities only; see the arrays') and explains the core behavioral caveat (ID mismatch). This is sufficient for an agent to correctly invoke the tool on 2-parameter inputs and interpret the 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?

The schema already documents the before/after alternatives (file, erdId, sql, dbml), so the description doesn't repeat those. It does add meaningful context about 'a side freshly parsed from text' having different IDs, which directly clarifies the behavior for sql/dbml inputs and complements the schema rather than merely restating 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 opens with 'Compares two ERD sources' and explicitly lists the compared components (entities/attributes/domains/relationships) and the 'unchanged omitted' behavior. This clearly distinguishes it from sibling tools like import_sql/import_dbml, making its purpose 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 description explicitly frames this as 'a dry run before full-replace import_sql/import_dbml', providing a direct use-case and naming the alternative tools. It also warns that a side 'freshly parsed from text has different ids' and that behavior matches 'full replace', guiding the agent on when the results are expected and how to interpret them.

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. It discloses stable-id matching for renames, destructive changes commented out, [WARNING] comments for unsupported changes, the impact of baseline lineage (file/erdId) versus fresh SQL/DBML, and requirements for Pro plan and login. This is comprehensive 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 three sentences, each dense with information. It front-loads the primary action and output traits, then explains matching behavior, and finally access requirements. No redundant phrases 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?

Given the tool's complex input (multiple forms for baseline/target) and lack of output schema, the description adequately covers the main behavior and output characteristics. It mentions the script includes commented destructive changes and WARNING flags, but does not detail the exact output format or error cases. It does address auth and plan requirements.

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 provides descriptions for all three parameters (100% coverage), so the baseline is 3. The description adds value by explaining how the choice of baseline type (file/erdId vs SQL/DBML) affects rename matching, which is not in the schema. This goes beyond simple parameter definitions.

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 generates a migration (ALTER) script from a physical diff between baseline and current model. It specifies key output characteristics (renames preserved, destructive changes commented out, unsupported changes flagged), which strongly distinguishes it from siblings like export_sql or diff_erds.

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 context that this tool is for generating migration scripts, but does not explicitly compare with alternatives or state when not to use it. It mentions lineage-based rename preservation versus fallback for fresh SQL/DBML, which hints at usage conditions but without explicit exclusions or alternative recommendations.

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, but it only states the output format. It does not mention whether the operation is read-only, any side effects, or what happens with invalid sources. The behavior is largely implicit.

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, focused sentence that clearly conveys the tool's purpose. No filler or redundancy. It is appropriately front-loaded and easy to parse.

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 export tool but lacks usage context and exploration of edge cases. Without an output schema, the phrase 'DBML text' hints at the return format, but it does not clarify the 'project' notion or how the source is selected. Basic 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?

The schema description covers the single 'source' parameter thoroughly with an anyOf structure and per-variant descriptions. The tool description adds no parameter-specific information, so the schema carries the semantic load. Given 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 uses a specific verb 'Exports' with a clear resource 'the project as DBML text', which distinguishes it from siblings like export_sql and export_alter_sql. The format 'DBML text' is precise and leaves no ambiguity about the tool's output.

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 offers no guidance on when to use this tool versus alternatives like export_sql or import_dbml. It simply states the action without context, prerequisites, or exclusions, leaving the agent to infer its use case.

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 burden. It discloses a behavior (project dialect fallback) beyond the schema, but does not mention return format, authorization, or side effects. For a simple read-only export, 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?

Two sentences, front-loaded with the purpose, no wasted words. The description is concise and to the point.

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 with two parameters fully described in the schema. The description covers purpose and a default behavior. It does not explicitly state the return value, but with no output schema and the nature of an export tool, this is acceptable. The description is complete enough for an agent to select and invoke it.

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 baseline is 3. The description adds a note about the dialect parameter's default behavior, which is useful but not extensive beyond what the schema already 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 tool exports the physical model as CREATE TABLE SQL, using a specific verb and resource. It distinguishes from siblings like export_dbml and export_alter_sql by specifying the exact output 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 implies use when needing DDL for the physical model and provides a useful default dialect behavior. It does not explicitly mention alternatives or exclusions, but the context is clear enough for most agents.

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 transparency burden. It discloses two non-obvious behaviors: unregistered words go to warnings, and using a workspaceId source reads the latest workspace-standard master. This adds meaningful context beyond the tool name, though it doesn't cover all potential side effects or return details.

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 concise sentences, front-loading the core action with no filler. The parenthetical about unregistered words and the workspaceId condition are efficiently integrated without bloating the text.

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 reasonably complete for a two-parameter tool, covering the generation process and warning behavior. However, it does not specify the return format or any error conditions, and given the absence of an output schema, this leaves some ambiguity about what the agent should expect.

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 50% because logicalName lacks a description in the schema. The description compensates by explaining the parameter's role ('logical name') and adding workspace-specific behavior. However, it does not elaborate on file/erdId source variants, which are already described in 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 states the tool generates a physical name from a logical name using a word list and naming rules, with a specific action and resource. It distinguishes itself from sibling tools like check_naming or propose_dictionary_word by emphasizing generation rather than validation or proposal.

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?

Usage context is implied—provide a source and logical name to get a physical name—and the description adds a conditional behavior for workspaceId sources. However, it does not explicitly mention when to use this tool versus alternatives like check_naming or propose_dictionary_word, nor does it provide exclusions.

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. It discloses the matching precedence and duplicate handling, which is valuable behavioral context. However, it does not mention error behavior, output format, or whether the operation is read-only (though 'get detail' implies read-only).

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 front-loaded with the core purpose, then clarifies the lookup behavior. Every sentence adds value with no redundant information.

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

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

For a simple lookup tool with 3 parameters and no output schema, the description provides essential invocation details: what is returned (attributes and physical mapping) and how the entity is identified. It does not elaborate on physical mapping, but the description is adequate for selecting and calling this 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 low (only source is described), but the description adds meaning to entityId (preferred) and logicalName (fallback, exact match, first hit on duplicates), partially compensating for the missing schema descriptions. The source parameter is already well-documented in 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 states the tool's purpose: retrieving entity detail including attributes and physical mapping. It distinguishes from sibling tools like list_entities (which lists entities) and get_erd_overview (which provides an overview), though it lacks an explicit verb.

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 guidance on how to select the target entity (prefer entityId, otherwise exact logicalName match, first hit on duplicates), but it does not explicitly state when to use this tool versus alternatives like list_entities or when not to use it. Usage is implied by the tool name and purpose.

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 carry the transparency burden. It states the tool 'Returns' a summary, implying read-only behavior, but it does not disclose side effects, error scenarios, or access requirements. The mention of 'standard link status' adds some specific context but remains undefined.

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 result. Every word earns its place, with 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?

The tool is simple, with one well-documented parameter and a brief enumeration of return categories. While there is no output schema, the description adequately conveys the main output types ('entity/relationship/domain/word-list stats, standard link status'), though terms like 'stats' and 'standard link status' could be more explicit. Overall, it is sufficiently complete for the tool's simplicity.

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 provides 100% coverage of the single 'source' parameter, including the exactly-one-of file/erdId constraint. The description adds no further parameter details, 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 uses the specific verb 'Returns' with a clear resource ('ERD summary') and enumerates the contents (stats, link status). This clearly distinguishes it from sibling list/get tools like list_entities or get_entity, which focus on individual components rather than an aggregate overview.

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 explicit guidance is given on when to use this tool versus alternatives. The name and description imply it is the right choice for an ERD-level overview, but there is no direct comparison or exclusionary language, leaving usage inferred 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 burden of behavioral disclosure. It transparently reveals the destructive nature ('Fully replaces'), a key side-effect ('project id preserved'), a constraint ('dialect fixed to mysql'), and an error condition ('Rejected as invalid_source when no tables are found'). This gives an agent a solid grasp of side effects and failure modes.

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 tight two-sentence statement. It front-loads the primary behavior and then adds important secondary constraints and error handling. 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 two-parameter mutation tool with no output schema, the description covers the core purpose, key side effects, a constraint, and a specific error case. It does not mention the return value on success, but this is not critical given the tool's simplicity and the fact that the main outcome is a replaced ERD.

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 50%, and the description adds meaning to the 'dbml' parameter by calling it 'DBML parse result' and clarifies that 'source' refers to an existing ERD to be replaced. However, the source schema already provides good descriptions for file/erdId, and the description does not add further detail about the expected format or relationships between parameters.

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 primary action: 'Fully replaces an existing ERD with the DBML parse result.' The verb 'replaces' plus the specific resource (ERD) and result (DBML parse) make the purpose unambiguous, and it distinguishes from siblings like export_dbml (export) and import_sql (SQL import).

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 use case: when you want to replace an existing ERD with DBML content. However, it does not explicitly mention alternatives or exclusions (e.g., 'for importing SQL, use import_sql'), so it lacks direct comparative 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 provided, the description correctly carries the burden. It clearly discloses the destructive 'fully replaces' behavior, notes that the project id is preserved, and mentions the invalid_source error condition when no tables are found. This goes beyond the schema and gives the agent important risk-related 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 only two sentences, front-loaded with the core behavior, and every word adds value. It is succinct without sacrificing necessary caveats.

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 three-parameter tool with no output schema, the description covers the key contextual aspects: destructive replacement, project preservation, and a relevant error condition. It does not explain the success return value, but the core invocation context is adequately 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 already documents the required sql and source parameters with descriptions, and the dialect parameter has an enum with a default. The description does not add further parameter-level meaning, but it does not need to given the schema coverage of 67%. 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's function: it replaces an existing ERD with the result of parsing SQL, while preserving the project id. This distinguishes it from sibling tools like import_dbml and makes the resource and action explicit.

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: use this when you want to replace an existing ERD with a SQL parse result. However, it does not explicitly mention when not to use it or contrast it with alternatives like import_dbml, so some guidance is missing.

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 full burden for behavioral disclosure. It explicitly states 'Read-only — queries only the information schema/catalog; never reads table data,' addresses data privacy ('database URL is used by this local process only and is never sent to Sqemo servers'), and notes the Pro plan requirement. This goes beyond a basic purpose statement.

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

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

The description is three sentences that front-load the primary purpose, then add safety and authentication details. Every sentence contributes unique information without redundancy, making it appropriately concise and well-structured.

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

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

Given the tool has no annotations and no output schema, the description covers purpose, safety, privacy, and access requirements. The main missing piece is the return value or confirmation behavior after the import, but the complexity is moderate and the schema descriptions fill in parameter details, so it is reasonably 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 already provides detailed descriptions for all three parameters (url, source, dbSchema), covering the connection URL, target ERD selection, and schema defaults. The tool description adds no additional parameter-level detail, but since schema coverage is 100%, it meets the baseline of 3. The 'full replace' behavior is a tool-level trait, not a parameter semantic.

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 imports the schema of a live PostgreSQL/MySQL database into an existing ERD, with the specific behavior 'full replace, project id preserved.' This distinguishes it from sibling import tools like import_sql or import_dbml, which work with file formats rather than live database introspection.

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 context for when to use the tool: when you need to introspect a live database schema into an existing ERD. It mentions prerequisites (Pro plan, login) and the read-only nature, but does not explicitly contrast it with alternatives like import_sql/import_dbml, so it earns a 4 rather than 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?

With no annotations provided, the description carries the full burden for behavioral disclosure. It thoroughly enumerates what the lint covers, but it does not explicitly state whether the operation is read-only, what output/return format it produces, or any side effects. Since 'lints' implies analysis, some transparency is present, but the missing output/error behavior is a 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, information-dense sentence enumerating many lint categories, followed by a comparative phrase. Each item adds value regarding the tool's scope, but the density makes it slightly less scannable than ideal, though it remains concise without redundancy.

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

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

The description covers the full scope of lint operations and differentiates from validate_erd, and the input schema fully covers parameter usage. However, with no output schema, the description does not mention the return format or report structure, leaving a gap for agents that need to interpret results. Overall, it is adequate for selection and 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 fully documents the single 'source' parameter with an anyOf structure for a local file or server ERD, achieving 100% coverage. The description adds no parameter-specific information, but this is unnecessary given the schema's clarity, 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 specifies the tool's purpose with a specific verb ('Lints') and resource ('the whole project'), followed by a detailed list of check categories (structure, referential integrity, duplicates, identifier length limits, auto-increment, naming standard). It distinguishes itself from validate_erd by contrasting quality/standards orientation with structural validity.

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 'Quality/standards oriented, unlike validate_erd (structural validity)', which names an alternative and clarifies when to use this tool (for quality/standards checks) versus validate_erd (structural validity). This provides clear usage guidance, though it does not mention other overlapping tools like check_naming.

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 burden of behavioral disclosure. It adds one behavioral note (workspace-standard master behavior) and hints at return content, but omits details like read-only nature, error handling, or output format beyond name/data type.

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

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

Two concise sentences, front-loaded with the core purpose and a single clarifying caveat. No 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?

The tool is simple with one well-documented parameter and no output schema. The description covers the return fields (name, data type) and source-specific behavior, which is sufficient for most use cases, though it lacks explicit error/edge-case info.

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 baseline is 3. The description adds value by explaining the workspaceId variant's special behavior ('reads the latest workspace-standard master'), which goes beyond the schema's generic source description.

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 ('Lists'), a clear resource ('domain definitions'), and the included fields ('name, data type'). This distinguishes it from sibling tools like list_relationships and list_erds.

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 by listing domains from various sources and highlights a special behavior for workspaceId sources, but it does not explicitly state when to prefer this tool over alternatives or when not to use 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?

With no annotations, the description carries the full burden of behavioral disclosure. It only states that entities are listed with particular fields, and gives no information about read-only behavior, error conditions, or return format. This is insufficient for a tool without annotation support.

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 front-loads the verb and result fields. It is concise, with no wasted words 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 no output schema, the description does name the fields returned, which is helpful. However, it omits prerequisites (e.g., valid source path or ERD ID), error behavior, and any usage context. For a simple list tool with a fully described schema, this is minimally adequate but has clear 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?

The input schema fully describes the single 'source' parameter, including a union type of local file or server ERD with detailed descriptions. Since schema coverage is 100%, the description does not need to add parameter details, and 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 lists entities and specifies the fields returned (logical name, physical name, attribute count). It distinguishes from sibling tools like list_relationships by focusing on entities, though it does not 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?

No guidance is provided on when to use this tool versus alternatives such as list_relationships or get_entity. There is no mention of prerequisites, exclusions, or best-use 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It adds useful context about ownership permissions and login requirements, but it does not describe return format, pagination, or side effects. For a list operation, the lack of explicit read-only confirmation 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?

The description is two sentences, front-loaded with the core function ('Lists server ERDs') and followed by a concise prerequisite. Every sentence earns its place; there is no fluff or redundancy.

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

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

For a simple, parameterless list tool, the description covers the core purpose, scope, and a key prerequisite. While it does not explain return values or ordering, the absence of an output schema and the simplicity of the operation mean the description is reasonably complete. It could be improved by noting what the response contains (e.g., ERD IDs/names).

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 input schema has no properties, so schema coverage is effectively 100%. The baseline for 0-param tools is 4, and the description does not need to add parameter details. It correctly explains the resource scope instead.

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

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

The description clearly states it lists server ERDs with the owned/shared scope, which is a specific verb+resource combination. It does not explicitly differentiate from sibling tools, but the resource type (ERDs vs relationships, workspaces) makes the purpose clear enough.

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 a clear prerequisite (requires login) and the command to do so, which is a form of when-to-use guidance. However, it does not explain when to prefer this over alternatives like list_relationships or list_workspaces, so the guidance is implied rather than explicit.

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 exist, so the description must cover behavior. It discloses login requirement and ordering, but does not explain the required source parameter, pagination, or that it's read-only (implied by 'lists'). The 'mine' clarification is helpful but ambiguous without a corresponding 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?

Three short sentences, each adds value, front-loaded with the main action.

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 list tool, it provides enough to get started: what, order, filter, auth. But it lacks guidance on choosing between file/ERD/workspace source and the meaning of 'mine' in the context of the schema. Given no output schema, a bit more detail would help.

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

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

The schema covers 50% of parameters (source has a description, status does not). The description adds 'mine' semantics but doesn't explain the source choices or status values, so it only partially compensates.

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?

Clearly states it lists the proposal queue, specifies ordering and scope (word/domain, newest first, mine), and distinguishes it from sibling list tools like list_relationships and list_erds.

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 context that this is the workspace-standard queue and filterable by status, implying when to use it. However, it does not explicitly name alternatives or exclusions, so it's not 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?

With no annotations, the description carries the full burden for behavioral transparency. It discloses the output fields, which is useful, but it does not explicitly state that the operation is read-only, nor does it mention side effects, permissions, or error behavior. The word 'Lists' implies a safe read, providing some value.

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, focused sentence that front-loads the core action ('Lists relationships') and efficiently packs the output details into a parenthetical. Every word contributes value, making it appropriately sized and well-structured.

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

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

The tool has a simple signature with one fully documented parameter and no output schema. The description specifies the fields returned in each relationship, which is adequate for a basic list tool. It does not mention return format or pagination, but for this low complexity, the description is reasonably 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 description does not discuss the 'source' parameter; however, the input schema fully documents it with a clear explanation of the file vs erdId union. Since schema description coverage is 100%, the description adds no additional meaning beyond the schema, 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 'Lists relationships' and specifies the components of each relationship (endpoint entity names, cardinality, identifying flag). This is a specific verb+resource that distinguishes it from sibling tools like list_entities and list_erds.

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 versus alternatives, nor does it mention any exclusions or prerequisites. The intended usage is only implied by the name and the generic list verb, so it falls short of providing clear 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?

With no annotations provided, the description carries the full transparency burden. It discloses ordering behavior ("owner first"), auth requirements ("Requires login"), and what additional information is returned (whether a standard exists). It doesn't explicitly state read-only or return format, but the verb "Lists" makes that obvious and the core behaviors are 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 a single sentence with no unnecessary words. It front-loads the verb and resource, then packs relevant details (ordering, standard existence, login requirement) 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?

Given the tool's simplicity (no parameters, no output schema), the description is largely complete. It identifies the primary output (workspaces), an ordering nuance, the auth prerequisite, and an extra data point. Minor gaps like pagination or exact return structure are not critical for this simple list tool.

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

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

The tool has zero parameters, so the baseline score is 4. The description correctly omits any parameter details, and no addition is necessary.

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 ("Lists"), the resource ("my workspaces"), and adds specific details: owner-first ordering and whether a standard (word list + naming rules) exists. This distinguishes the tool from sibling list tools like list_entities or list_domains.

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 by scoping to "my workspaces" and noting "Requires login," implying when it should be used. It does not explicitly name alternatives or exclusion criteria, but for a simple parameterless list tool, this 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?

With no annotations, the description carries the full burden of behavioral disclosure. It reveals login requirement, duplicate handling, source resolution via glossaryLink, and the owner approval process. It doesn't describe success return values or withdrawal options, but the key behaviors are 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 sentences, no fluff. It front-loads the core purpose, then packs source resolution and duplicate behavior into the next two sentences, and concludes with the auth requirement. Every sentence 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 tool with 7 params, no annotations, and no output schema, the description covers the essential aspects: what it does, source variants, duplicate outcomes, and auth. It does not specify success return format or integration with list_proposals/withdraw_proposal, but the core workflow is understandable.

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 57% of parameters, and the description adds value by explaining how source works (workspaceId vs linked ERD resolved via glossaryLink) and by mapping duplicate results to registered/pending words. The remaining parameters (englishName, abbreviation, description, note) are self-explanatory by name.

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: proposing a new word for the workspace standard's word list, with owner approval. It distinguishes itself from direct dictionary modification tools like upsert_dictionary_word by emphasizing the proposal workflow.

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 (proposing a new word, with source options) and explains duplicate behavior (already_exists vs already_proposed). It also mentions login requirement. However, it does not explicitly name alternative tools or state when not to use it, 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?

With no annotations, the description carries the disclosure burden. It provides meaningful behavioral details: partial matching, case-insensitivity, a 50-result cap, and workspace-specific mastery reading. It does not cover return format or side effects, but for a search tool these are less critical and the key behaviors are well disclosed.

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, front-loaded with the core purpose, and includes only relevant details. Every clause adds information without repetition 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?

For a search tool with two parameters and no output schema, the description covers the search scope, case sensitivity, result limit, and a workspace-specific behavior. It could mention return values or that file/erdId sources behave differently, but those are minor gaps compared to its overall completeness.

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 parameters are already documented. The description adds valuable semantics by explaining that the query is a partial-match across specific fields and that workspaceId triggers reading the latest workspace-standard master, enriching the schema's basic descriptions.

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 tool as a partial-match word-list search across logical/physical/abbreviation/English/synonyms, with specific behaviors (case-insensitive, max 50). This differentiates it from sibling tools like list_erds or upsert_dictionary_word, which serve different purposes.

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 by explaining what the tool searches and its workspace-specific behavior, but it does not explicitly state when to use this tool over alternatives, nor does it mention any exclusions or prerequisites. The workspace-standard note gives context but not comparative 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 provided, the description carries the burden of behavioral disclosure. It explicitly discloses the non-retroactive nature of the update and mentions that warnings will note this. It doesn't cover reversibility or validation behavior, but the key side-effect that matters to users is addressed. The 'partially updates' phrasing also implies a merge-like behavior, 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?

The description is two sentences long, front-loads the action and resource, and includes a critical warning without any fluff. Every sentence earns its place, and the structure is easy to parse.

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 complexity (5 parameters, 1 required, no output schema, no annotations), the description covers the essentials: purpose, timing, and a key behavioral caveat. It doesn't describe return values or error handling, but these are not required without an output schema. Overall, it is sufficiently complete for an agent to decide when and how to invoke it.

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

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

The description maps the high-level rule categories to specific parameters ('delimiter' to separator, 'case' to casing, etc.), which adds meaning beyond the schema. It also clarifies that the update is partial, meaning unspecified fields remain unchanged—an important semantic not in the schema. With 40% schema coverage, this compensation is necessary and well-executed.

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 function: 'Partially updates the naming rules' and enumerates the specific aspects (delimiter, case, unknown-word handling, self-reference role prefix). This distinguishes it from sibling tools like check_naming and generate_physical_name, which focus on validation and generation rather than configuration.

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 contextual guidance: 'Existing physical names are not regenerated retroactively... set the rules before modelling.' This tells the agent when to use the tool relative to other actions. It does not explicitly mention alternatives or exclusions, but the timing guidance is strong enough for most use cases.

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 reveals critical side effects: primaryKey=true forces nullable=false and propagates child FKs; a domain decides the data type; autoIncrement has dialect-specific SQL export and applies only to primary keys. This far exceeds minimal expectations.

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, each dense with distinct information: create vs update semantics, primaryKey constraints, domain precedence, and autoIncrement dialect behavior. No filler or repetition, and the most important distinction 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?

Given 11 parameters, no annotations, and no output schema, the description provides the most critical behavioral nuances. It could mention what happens if validation fails or what the tool returns, but it covers the core usage and side effects sufficiently for an agent to select and invoke 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?

Schema description coverage is only 18%, so the description must compensate. It adds meaning to attributeId, logicalName, primaryKey, domain, and autoIncrement, explaining their roles and interactions. However, it leaves unique, dataType edge cases, and defaultValue handling (beyond the schema's note) implicit, so it is not fully comprehensive.

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 a dual create/update mode for attributes, specifying that creation requires no attributeId and logicalName, while updates use attributeId and only modify provided fields. This distinguishes it from sibling upsert tools (entity, relationship, domain) by focusing on attribute-specific behavior.

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

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

The description gives explicit conditions for when to use the create path vs the update path based on the presence of attributeId. It also notes key behavioral triggers like primaryKey=true and domain overriding dataType. It does not explicitly name alternative tools, but the sibling names and the tool's attribute-specific scope make selection obvious.

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 transparency burden. It discloses two meaningful behaviors: physical words are normalized to uppercase, and standard-linked dictionaries are rejected with dictionary_is_linked. This is more than typical, though it omits details about permissions and return values.

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

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

The description is three concise sentences with the core operation front-loaded. There is no redundant language, and each sentence adds a distinct piece of information: add/update mode, normalization behavior, and a rejection scenario.

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 main purpose and a couple of edge behaviors, but for a 7-parameter tool with no output schema, it leaves gaps: it doesn't explain whether logicalWord and physicalWord are still required for updates (they are in the schema), nor the return value. It also doesn't mention the alternative propose_dictionary_word, which might be more appropriate in some contexts.

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 only 14%, so the description must compensate. It clarifies the roles of logicalWord and entryId (create vs update) but leaves description, englishName, and abbreviation undefined, relying on the schema for source. This is partial compensation for an otherwise low-coverage 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 explicitly states the tool's action: 'Adds a glossary entry (upsert by logicalWord) or updates one (entryId given).' It also mentions a rejection condition, clearly distinguishing it from sibling tools like delete_dictionary_word and propose_dictionary_word.

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 the two distinct usage modes (insert vs update) and the linked-dictionary rejection, giving clear context for when to use it. However, it does not explicitly mention alternatives or exclusion scenarios, such as using propose_dictionary_word for proposal workflows.

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. It discloses the upsert behavior and that the existing description is preserved if omitted, adding useful behavioral nuance. However, it does not mention what happens to other fields, error conditions, or prerequisites, leaving significant behavioral gaps.

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, front-loaded with the core upsert behavior and a key preservation nuance. Every word serves a purpose, and there is 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?

For a 5-parameter mutation tool with no annotations and no output schema, this description is incomplete. It fails to explain the source and dataType parameters, the relationship between source and the domain, or how updates handle unspecified fields beyond description. An agent would likely need additional details 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 description coverage is 20%, and the tool description compensates by explaining name (upsert key), domainId (update trigger), and description (preserved). However, source and dataType are not addressed in the description, and dataType lacks any schema description, leaving a meaningful gap in parameter understanding.

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 explicitly states that the tool creates a domain by name (upsert) or updates one when a domainId is given. This clearly defines the verb, resource, and the distinguishing condition between create and update, making it distinct from sibling tools like list_domains or delete_domain.

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: when you have a domain name to upsert or a domainId to update. It doesn't explicitly name alternatives or exclusions, but the conditional semantics are self-explanatory. This earns a 4 due to the absence of explicit alternatives.

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. It discloses that the tool mutates data by creating or updating, describes the partial-update behavior (only provided fields change), and notes that the physical name is derived automatically. This covers the key behavioral traits, though it doesn't mention explicit side effects such as whether the operation is idempotent or what happens if an entityId doesn't exist.

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, front-loaded with the core action, and no redundant wording. Every sentence delivers meaningful guidance, making it exceptionally concise.

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

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

For a CRUD upsert tool with no output schema and no annotations, the description is largely complete: it defines create vs update semantics, notes required fields, and explains the derived physical name. Minor gaps exist (e.g., return value, error conditions), but these are not essential for tool selection and 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 schema covers only 25% of parameters (source is described). The description adds meaning to entityId (present = update, absent = create) and logicalName (required for create), and implies that the description parameter can be partially updated. However, it doesn't fully explain all parameters or compensate entirely for the low schema coverage.

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 dual purpose: create an entity when no entityId is provided, or update (upsert) an existing one when entityId is given. It names the specific resource (entity) and the conditional create/update behavior, which distinguishes it from sibling tools like upsert_attribute or upsert_relationship.

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 tells when to treat the operation as a create (no entityId, logicalName required) and when to treat it as an update (entityId given, only provided fields change). This gives clear guidance on the two usage modes, though it doesn't discuss alternatives or exclusions relative to other tools.

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

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

With no annotations provided, the description carries the full burden and discloses key behaviors: automatic FK derivation, precedence of sourceEnd/targetEnd over cardinality, referential action semantics including the 'noAction' revert, and constraintName auto-generation on empty string. It does not mention failure scenarios but covers the main side effects.

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

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

The description is three sentences long, front-loaded with the primary purpose, and every clause adds essential detail about precedence and parameter behavior. There is no fluff or repetition of schema information, making it efficient and well-structured.

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

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

Given 11 parameters, no annotations, and no output schema, the description covers the main operational flows but misses important context such as what sourceEntityId/targetEntityId expect (names or IDs), the meaning of cardinality values, and what happens on invalid input. It is adequate for basic selection but leaves significant gaps for a 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 only 9%, so the description must compensate. It adds meaning to relationshipId (create vs update), sourceEnd/targetEnd precedence, onDelete/onUpdate referential actions, and constraintName behavior. However, it leaves sourceEntityId, targetEntityId, cardinality values, and relationshipType unexplained, which is a minor gap.

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 creates a relationship when no relationshipId is provided and updates one when relationshipId is given. This specific verb+resource view distinguishes it from sibling tools like list_relationships and delete_relationship, and also outlines the two distinct modes.

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 context for when to use create vs update by explicitly tying the presence of relationshipId to the operation. While it doesn't explicitly name alternative tools, the conditions for using this tool versus creating/updating entities or deleting relationships are implied and practical.

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. It discloses the return shape ({ valid, errors }), which is useful behavioral information given no output schema. However, it does not state whether the tool has side effects (e.g., modifies anything) or requires specific permissions, leaving ambiguity for a validation 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 a single, front-loaded sentence that efficiently communicates the core function and return value. Every word earns its place, with 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?

Given the tool's simplicity (one parameter, well-documented schema), the description provides the essential return format and purpose. However, it lacks usage guidance and does not address how this validation differs from sibling validation tools. For a tool with no annotations and no output schema, this is reasonably complete but not exhaustive.

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 thoroughly explains the 'source' parameter, including the two accepted forms (local file or server ERD id). The description adds no additional meaning about parameters, 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 clearly states the tool validates project structure and referential integrity, using the specific verb 'validates' and identifying the resource. It does not explicitly differentiate from sibling tools like lint_erd, which also likely performs validation, but it adds specificity by mentioning referential integrity.

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 on when to use this tool versus alternatives such as lint_erd, check_naming, or check_db_drift. The description only states what it does without any context on appropriate scenarios or exclusions.

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. It discloses the login requirement, the ownership restriction, and the not_found error behavior for invalid proposals. It does not describe the success return value but covers the most critical behavioral traits.

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 short sentences, front-loaded with the main verb and resource. The second sentence adds edge cases and auth requirement without any 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 one-parameter tool with no output schema and no annotations, the description covers the essential context: action, target scope, failure conditions, and login requirement. It could mention the success response, but the description is sufficient for correct selection and 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 has 100% coverage, with the proposalId parameter described as 'Proposal id from list_proposals'. The description reinforces the precondition of being 'your own pending' but adds no syntax or format details beyond what the schema already 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 action ('Withdraws') and the resource ('your own pending proposal'), making the tool's purpose unambiguous. It also distinguishes from siblings like propose_dictionary_word and list_proposals by specifying the scope and behavior for invalid targets.

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: only 'your own pending proposal' should be withdrawn, and 'Proposals by others or already processed return not_found'. This effectively tells the agent when not to use the tool, though it does not explicitly name alternative tools.

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