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

No annotations are provided, so the description carries the full behavioral burden. It discloses key side effects: verification of the connection, auto-ingestion of models, environment variable substitution in credentials, and defaults like auto_ingest. It stops short of explaining failure behavior, whether an existing datasource is overwritten, or how connection_string interacts with individual credentials.

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 purpose is front-loaded in the first two sentences, followed by a compact Arg list and a useful invocation example. Every element earns its place: the summary, parameter explanations, constraints, defaults, and example. There is 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?

Given the tool's complexity, the description is nearly complete: all parameters are explained, constraints are noted, and a concrete example is provided. It does not need to explain return values because an output schema exists. Minor gaps remain around credential precedence when connection_string is used alongside individual fields and the exact behavior when auto_ingest is false.

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

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

Schema description coverage is 0%, but the description compensates fully by documenting all 12 parameters with additional meaning: supported type values, defaults, an example port, schema mutual exclusivity, and connection_string as an alternative. This goes well beyond the bare input schema and gives an agent what it needs to construct valid arguments.

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

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

The description opens with a specific action and resource: 'Create a database connection, verify it, and auto-ingest models.' This clearly distinguishes it from sibling tools like list_datasources, edit_datasource, and ingest_datasource_models. It also lists supported database types, making the tool's scope 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 clearly conveys when to use the tool: when creating a datasource and optionally ingesting models. It also provides parameter-level usage guidance, such as connection_string being an alternative to individual fields and schemas/schema_name/all_schemas being mutually exclusive. However, it does not explicitly name alternative tools or state 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 to lean on, the description carries the full burden for behavioral disclosure. It explains mutual exclusivity, that query-backed models save source_queries, that columns are auto-introspected from query results, and how variables map to query_variables. It does not detail failure conditions, idempotency, duplicate-name behavior, or permission requirements, but it is substantially transparent for a create operation.

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 long, but the tool's complexity justifies most of the length. It is well-structured with clear mode examples followed by an Args section. Some examples partially duplicate the function signature, but overall the information is organized and front-loaded with the core decision between table-based and query-based creation.

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, the absence of annotations, and 0% schema description coverage, the description provides nearly everything needed to invoke the tool correctly: parameter semantics, nested dict schemas, mode selection, mutual exclusivity, auto-introspection behavior, and variable handling. The output schema covers return-value expectations, so the description need not explain them.

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 0% description coverage, so the description is the only documentation for all 9 parameters. It comprehensively explains each parameter with examples, nested object structures, allowed types, constraints like uniqueness, and mutual exclusivity rules. This far exceeds what the bare schema provides.

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

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

The description clearly states the tool's purpose: creating a new semantic model. It also disambiguates from siblings by describing the two supported inputs (table-backed vs query-backed) and explicitly calling them 'new' models, which distinguishes this from edit_model and other sibling tools.

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

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

The description gives clear context on when to use table-based vs query-based creation, and references list_datasources as the source for data_source values. However, it does not explicitly state when not to use this tool versus closely related siblings like edit_model or ingest_datasource_models, so the guidance is strong but not explicit about 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the deletion action but does not mention whether deletion is irreversible, whether it only removes configuration or also underlying data, whether it cascades to dependent models, or what happens if the datasource name does not exist. For a destructive tool, this is a meaningful 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 short and front-loaded with the core purpose. The Args section is brief but repeats what the schema already structurally conveys. It earns its place by adding parameter context, though it could be slightly tighter.

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 one-parameter tool this is close to minimally viable, but the destructive nature of the operation requires more context. The description does not explain the scope of deletion, reversibility, side effects, or error behavior. Without annotations, an agent cannot fully assess the consequences of invoking 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 description coverage is 0%, so the description must compensate for the bare 'name' property in the schema. The Args section clarifies that the name is the datasource name to delete, which provides actionable meaning beyond the schema's generic 'Title: Name'. It fully covers the single required parameter.

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

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

The description states a specific verb and resource: 'Delete a datasource configuration.' This clearly distinguishes it from sibling tools like create_datasource, edit_datasource, and delete_model. The agent knows exactly what action this tool performs.

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 edit_datasource or delete_model. There are no explicit conditions, prerequisites, or warnings about when deletion is appropriate. Usage is only implied by the tool's name and one-line description.

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 responsibility for disclosing behavioral traits. It states that a semantic model is deleted, but it does not mention whether deletion is irreversible, whether it cascades to dependent objects, whether permissions are required, or what side effects may occur. This is a significant gap for a destructive operation.

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 purpose is front-loaded in a single clear sentence, and the Args section adds only relevant parameter details. There is no filler or redundant wording; every line supports correct invocation.

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 tool's purpose and both parameters, and an output schema exists so return-value details need not be explained. However, for a destructive tool with no annotations, the absence of behavioral consequences and the vague priority-list reference leave the description incomplete for an agent that needs to invoke it safely in edge cases.

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

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

Schema description coverage is 0%, so the description must compensate, and it does. It explains that `name` identifies the model to delete and that `data_source` serves as a disambiguator when the same name exists in multiple datasources. The reference to priority list / single-match rules adds meaning, though those rules are not fully defined.

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

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

The description uses a specific verb and resource ('Delete a semantic model'), making it immediately clear what the tool does. It naturally distinguishes this from sibling tools like delete_datasource and create_model/edit_model, so there is no ambiguity about its core operation.

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 useful conditional guidance for when `data_source` is required, but it does not explicitly address when to use delete_model versus alternatives such as delete_datasource. The intended usage is implied by the tool name and first sentence rather than backed by clear selection rules.

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 accurately explains the default behavior (tables are included by default), the logic for list_tables, and the handling of schema_name including the edge case 'Ignored when list_tables=False.' This goes beyond the schema and gives the agent meaningful behavioral 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?

The description is well-structured: a one-sentence summary, a one-sentence usage context, and a concise Args list. Every sentence adds necessary information, and the most important scoping detail (verify before ingest) is front-loaded.

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

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

For a describe tool with an output schema, the description covers all needed call context: what it returns at a high level, how to use it in the datasource workflow, and complete parameter semantics. The presence of an output schema lessens the need to document return values in prose, so nothing critical is missing.

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

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

Schema description coverage is 0%, so the description must fully compensate for the bare parameter titles. It does: 'name' is sourced from list_datasources, 'list_tables' is explained with its default and effect, and 'schema_name' gets an example ('public'), its default behavior, and its interaction with list_tables. All three parameters are richly documented.

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

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

The description opens with a specific verb and resource: 'Show datasource details: connection status, available schemas, and (by default) the tables.' It clearly distinguishes this from sibling tools like list_datasources and ingest_datasource_models by framing it as the verification/exploration step between them.

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 when to use the tool: 'Use this after create_datasource to verify the connection and explore what's queryable before calling ingest_datasource_models.' This gives an agent a clear workflow position and eliminates ambiguity about where this tool fits among siblings.

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 says 'Update' and does not explain what happens when 'description' is omitted (leave unchanged vs clear to null), whether the datasource must already exist, or what side effects occur. This ambiguity is significant because the schema gives 'description' a default of null.

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 short, front-loaded with the purpose, and includes only a compact Args list that adds necessary parameter semantics. There is no filler or redundancy.

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

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

For a simple two-parameter tool with an output schema, the description is mostly adequate. However, it lacks guidance on optional parameter behavior, error cases, and when to prefer this tool over related datasource/model tools, leaving minor but real gaps for an agent deciding 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?

Schema description coverage is 0%, so the description must define the parameters. It does add meaning: 'Datasource name to update' clarifies that 'name' is an identifier, and 'New description for the datasource' clarifies the intended value. It stops short of explaining null/omission semantics, but still compensates for the bare 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 states a specific action ('Update') on a resource ('a datasource's metadata') and the Args section clarifies that 'name' identifies the target while 'description' supplies the new value. It is clear enough to distinguish from create/delete/describe datasource tools, though 'metadata' is somewhat broad.

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: use this when you want to update an existing datasource's metadata. However, there is no explicit when-to-use vs alternatives, no mention of when not to use it, and no comparison to sibling tools like edit_model or delete_datasource.

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 disclosure burden — and it does so thoroughly. It explicitly documents side effects: setting sql_table clears sql and source_queries; source_queries refreshes cached columns; new_data_source renames storage location; removals are processed before upserts; cardinality is descriptive only and does not affect join_type or query results. These are exactly the non-obvious behaviors an agent needs to predict outcomes.

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

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

The description is long, but the tool has 18 complex, interdependent parameters. The summary line is front-loaded, each parameter entry earns its place by explaining semantics and interactions, and the two examples clarify common usage patterns. The structure is logical: summary, parameter details, examples.

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 18 parameters, no schema descriptions, no annotations, and complex cross-parameter clearing rules, the description provides everything needed to call the tool correctly. It covers all parameters, side effects, valid values, and usage examples. An output schema exists, so explaining return values is unnecessary.

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

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

Schema description coverage is 0%, but the description documents every parameter in depth. It provides dict shapes for columns, measures, aggregations, joins, and remove; explains mutual exclusivity and clearing behavior; and gives concrete examples. This far exceeds the bare type/title info in the input schema.

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

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

The description opens with a specific verb and resource: 'Edit an existing model in a single call', followed by a precise list of capabilities: update metadata, upsert columns/measures/aggregations/joins, manage filters, and remove entities. The word 'existing' and the mutation-focused operations clearly distinguish it from siblings like create_model, delete_model, and inspect_model.

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

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

The phrase 'Edit an existing model' gives clear context that this tool is for modifying already-created models, not for creating or deleting them. It does not explicitly name alternatives or state 'use create_model for new models', but the usage context is strong enough for an agent to select it appropriately.

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

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

With no annotations, the description carries the full burden and it discloses the key side effect (cascading removal of memory:<id> references from entities lists) and the error behavior for invalid or missing ids. It does not discuss reversibility or permissions, but the destructive action and cascade are clearly stated.

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

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

The description is front-loaded with the core action, then efficiently explains cascade behavior, parameter formats, and error handling. No sentence is wasted, and the structure is scannable.

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

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

For a one-parameter deletion tool with an output schema, the description covers the operation, parameter semantics, side effects, and errors. The only minor gap is that it does not describe the output or return value, but that is already covered by the output schema.

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

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

Schema coverage is 0% and the description fully compensates: it defines id as the memory_id returned by save_memory, lists accepted forms (canonical strings including kb.policy-style ids and legacy ints), and explains int coercion. This is more precise than the bare 'Id' property 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?

States a specific action ('Delete a memory by id') with the exact resource and identifier. This clearly distinguishes it from sibling deletion tools like delete_model and delete_datasource because it targets memories.

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 establishes clear context: use this when you have a memory_id from save_memory and need to remove that memory. It does not explicitly name alternatives or exclusions, but the resource distinction plus the save_memory relationship makes the appropriate use 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 burden and does reasonably well: it states the return value, the ordering convention, and the empty-list default when unset. It does not explicitly say the operation is read-only, but 'Return' and the absence of side-effect language make that sufficiently clear.

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. The core action and resource are front-loaded, and the ordering and default behavior are provided in a compact parenthetical.

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

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

For a zero-parameter, getter-style tool with an output schema present, this description is complete. It communicates what is returned, the ordering, and the fallback value, leaving no meaningful ambiguity for an agent invoking the tool.

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

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

The tool takes zero parameters, so the baseline of 4 applies. There are no parameter semantics to document, and the description does not need to compensate for any 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 uses a specific verb ('Return') and a well-defined resource ('configured datasource priority list'), and clarifies ordering as most-preferred first. It is clearly distinguishable from siblings like list_datasources and set_datasource_priority.

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

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

The description implies the tool is used when the agent needs the current datasource priority ordering, but it does not explicitly mention when to prefer this over alternatives or any exclusions. The context is clear enough for a simple getter, but no alternative routing is provided.

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

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

With no annotations, the description carries the behavioral disclosure burden. It clearly states idempotence, that re-runs are additive only, that existing definitions are never overwritten, and that the result includes pending validate_models deletes. This is substantial transparency for a mutating tool, though it does not cover failure modes or permissions.

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

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

The description is front-loaded with the core purpose and the crucial idempotence guarantee, followed by the necessary parameter documentation. The wording around 'pending validate_models deletes' is slightly awkward, but every sentence earns its place given the lack of schema descriptions.

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 five parameters, mutual exclusions, and a mutating/additive behavior, the description provides enough context to invoke it correctly: source datasource, table filtering, schema selection, and the additive result. It does not explain return structure in detail, but an output schema exists and the behavioral guarantee is clear.

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

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

Schema description coverage is 0%, so the description must compensate with parameter details. The Args section explains each parameter, gives examples, defines empty-string behavior, and documents mutual exclusivity among schema_name, schemas, and all_schemas. This fully compensates for the missing schema 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 states a specific action ('Auto-discover tables in a database') and a clear outcome ('create / additively update semantic models'). It clearly differentiates from sibling tools like create_model and edit_model by focusing on automatic discovery rather than manual construction.

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: it operates on an existing datasource from list_datasources and is additive/idempotent, so it is safe to re-run. It does not explicitly enumerate when to choose this over create_model/edit_model, but the auto-discovery language makes the intended use case clear.

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 and meets it thoroughly. It discloses that the tool is a clean point-lookup with no fusion/ranking/cypher or bundled memories, explains batch error isolation ('one bad id does not sink the batch'), and details per-parameter behavior such as warnings vs silent no-ops and compact rendering differences. This is far beyond what the input schema alone would convey.

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 long but highly structured and front-loaded: core semantics first, then Collection and Batch mode specifics, then a well-organized Args section. Each sentence adds unique information and there is no filler or tautology. The length is justified by the tool's multiple modes and eight parameters.

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

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

Given the absence of annotations and the presence of only minimal structural schema, the description is remarkably complete. It covers all three invocation modes, output framing in markdown and JSON, error handling in batches, collection-view restrictions, per-parameter conditional behavior, and relationships to sibling tools. An agent has everything needed to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate, and it does. Every parameter receives meaningful explanation: reference formats including canonical forms, bare names, join paths, and memory:<id>; the required entity_type and its disambiguation role; compact behavior per kind; format options; num_rows/show_sql/sections being ignored with warnings for non-model entity types; and descriptions_max_chars applying to every kind. This is exemplary parameter documentation.

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

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

The description opens with a precise statement of what the tool does: 'Inspect EXACTLY one entity by reference and kind, a homogeneous BATCH when reference is a list — or the whole COLLECTION at a kind when reference is omitted / None.' It also distinguishes itself from search and notes that it subsumes models_summary and list_datasources. This leaves no ambiguity about the tool's purpose.

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 routes agents to search when they need contextual results and states that the collection view raises for unsupported kinds. It also names models_summary and list_datasources as subsumed by this tool. However, it does not mention the closely named sibling inspect_model or describe_datasource, leaving some uncertainty about when those should be chosen instead.

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 disclosure burden and does so thoroughly. It details always-emitted content, section-gated behavior, collapse behavior for omitted sections, the footer, unknown-section handling, SQL gating via `show_sql`, and truncation semantics. This gives the agent strong awareness of response shape and edge-case behavior.

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 long but tightly structured and front-loaded with the deprecation warning and core purpose. Every major behavior is organized under clear headers, defaults and edge cases are explicit, and there is no filler or vague wording.

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 an 8-parameter introspection tool with no annotations and an output schema, the description is unusually complete: it explains output composition, section subsetting, collapse behavior, SQL inclusion, format, and truncation. The only real gap is the undocumented `compact` and `data_source` parameters, which prevents a perfect score.

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 raw schema has no parameter descriptions, so the description compensates substantially for `model_name`, `num_rows`, `show_sql`, `format`, `sections`, and `descriptions_max_chars`, including a nuanced explanation of unknown `sections` values. However, `compact` and `data_source` are absent from the Args section, leaving their semantics to inference from titles and context.

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 ('Return') and resource ('semantic model') and defines the output as a 'complete-yet-compact view.' It also explicitly distinguishes itself from the sibling `inspect` tool by flagging DEPRECATED and directing the agent to use `inspect` instead, leaving no ambiguity about what this tool does.

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

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

The description is explicit about usage: it begins with 'DEPRECATED: use the inspect tool,' naming the alternative and telling the agent when not to choose this tool. It also gives clear guidance on section selection, defaults, and edge cases, so an agent knows exactly how to request the desired subset of output.

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 states that credentials are not shown, which is an important privacy/security behavior beyond the basic 'list' semantics. The read-only nature is implied by 'List' but not explicitly stated; a small gap, but the redaction disclosure adds meaningful transparency.

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 with no filler. The main purpose is front-loaded, and the second sentence adds routing guidance. 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 parameterless list tool with an output schema present, the description fully covers what the agent needs to decide whether to call it and what to expect. It also gives a pointer to the appropriate sibling for more detail, making the context 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 tool has zero parameters, so there is no parameter documentation needed. The description focuses on the output content instead, clarifying that only names and types are returned, which is the relevant semantic information for an agent.

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

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

The description clearly states the action ('List all configured database connections') and the scope of the result ('names and types only'), immediately distinguishing it from connection detail operations. It also explicitly differentiates from describe_datasource.

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 explicitly tells the agent when to use this tool versus an alternative: use describe_datasource for connection details and status. This is clear, direct routing guidance with no ambiguity.

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 and does well by detailing exactly what compact=True emits (name, description, column count, measure names, joins list) and what it omits. It also discloses the default behavior and the compact=False alternative. It doesn't discuss errors or side effects, but none are expected for a read-only summary tool.

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

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

The description is well-structured with a clear opening sentence followed by rendering details and an Args list. The DEV-1549 ticket reference is noise for an AI agent, but all other sentences earn their place by clarifying output behavior and parameter choices.

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 fully covers the parameters and output rendering modes, and an output schema exists to define the structured return shape. It could improve by naming sibling alternatives or noting datasource-not-found behavior, but for a summary tool with this complexity it is largely complete.

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

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

Schema description coverage is 0%, so the description must compensate, and it does. Each parameter is explained in the Args section: datasource_name references list_datasources, format names valid values and case-insensitivity, and compact explains default and behavioral impact. This adds substantial meaning beyond the bare input schema.

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

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

The description clearly identifies the tool's purpose: 'Brief summary of all (non-hidden) models in a datasource.' It specifies the resource scope (all non-hidden models) and gives a distinct action, though it doesn't explicitly contrast with siblings like inspect_model or describe_datasource.

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

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

The description gives clear context for when the tool would be useful—summarizing all models in a datasource—but it never explicitly states when to prefer this over siblings such as inspect_model or describe_datasource. It does explain usage for compact versus verbose output and format selection, but tool-alternative guidance is implied rather than stated.

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

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

With no annotations, the description carries the full burden and delivers richly: filters on measures are "automatically routed to HAVING," change/change_pct/time_shift are disclosed as calendar-aware and partition-safe with clean per-group resets, lag/lead are described as window functions with "NULL at edges," strict mode's error/drop behaviors and run-by-name rejection are stated, distinct_dimension_values' auto-dedup GROUP BY behavior and error-on-measure-reference are detailed, and dry_run/explain/show_sql modes are all explained.

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 long (~600 words), but the length is justified by 16 parameters and a complex formula grammar. It is well-structured with a front-loaded purpose sentence, per-parameter 'Args' sections, and a worked example. The 'run search first' precondition is buried at the end rather than near the front, which costs it a perfect score.

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 16-parameter tool with no annotations and zero schema descriptions, the description is remarkably complete: preconditions, parameter semantics, formula grammar, edge cases, error modes, and output format options are all covered, and the output schema covers return values. Minor gaps are the undocumented `variables` parameter and the unaddressed relationship to query_nested.

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

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

Schema description coverage is 0%, so the description must compensate — and it nearly does. It explains all three source_model forms with inline dict examples, enumerates measure formula functions with concrete examples, defines filter syntax and HAVING routing, specifies time_dimensions format, and adds meaning to order, whole_periods_only, strict, format, and distinct_dimension_values. Only the `variables` parameter receives no descriptive 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 first sentence, "Query data from a semantic model," states a specific verb plus resource, and the detailed parameter documentation (three source_model forms, measure formulas, filters, time dimensions) makes the operation unambiguous. It is clearly distinguishable from the introspection siblings (inspect, inspect_model, models_summary) and DDL siblings (create_model, edit_model).

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?

Explicit orchestration guidance is given: "Call inspect(reference="<ds>.<model>", entity_type="model") first" and "Before calling this tool, run search first... Read the returned memories and consider any matching example queries." However, it never names alternatives or exclusions — notably, it does not say when to use the sibling query_nested instead, so the when-not dimension 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?

With no annotations provided, the description fully carries the behavioral burden. It discloses engine auto-sorting, the last entry being the DAG root, required names for non-final stages, rejection of cycles/self-references/root references, silent dropping of unreachable stages, variable precedence, and the effects of `show_sql`, `dry_run`, and `explain`.

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 long but appropriately so for a complex DAG-based tool. It is front-loaded with the core purpose, then structured into semantics, arguments, an example, and an alternative-tool recommendation. Every section adds useful information without fluff.

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

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

The description is complete for a tool of this complexity: it covers DAG semantics, ordering, naming rules, error cases, variable precedence, flags, formats, and includes an end-to-end example. An output schema exists, so detailed return-value documentation is not required from the description.

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

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

Schema description coverage is 0%, so the description must compensate, and it does. Each parameter is explained, including defaults, placeholder substitution, precedence, and format options. It also explains that each query dict follows the same shape as the regular `query` tool's arguments and provides a concrete example.

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 opening line clearly states the tool's function: 'Run a multi-stage query as a DAG.' It also states the exact use case—when one stage depends on another—which distinguishes it from the sibling `query` tool for single-stage queries.

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

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

The description explicitly says when to use this tool: 'Use this when one stage depends on the output of another.' It also gives an explicit alternative and exclusion: 'For a single-stage query, prefer the regular query tool—its typed arguments give a more discoverable schema.'

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

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

No annotations are present, so the description carries full responsibility, and it delivers: it discloses join directionality rules, the min-hop objective, root_hint override semantics, and failure behavior. It also exposes the important constraint that root_hint cannot select a datasource.

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 long, but it is organized into purpose, algorithm, edge-case, and Args sections with no filler. The essential 'what it returns' and failure mode are 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?

Despite no annotations and an output schema that isn't shown, every decision-relevant behavior is covered: output examples, multi-stage fallback, and constraints on arguments. An agent has enough to call it correctly and interpret results.

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

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

Schema description coverage is 0%, but the Args block documents all four parameters with concrete examples and nuances: item syntax variants, datasource resolution, root_hint precedence, and format defaults. This fully compensates for the empty schema 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 opens with a specific verb ('Recommend') and resource ('root model'), and states the second output ('join-qualified reference path'). This clearly distinguishes it from query/query_nested siblings, which execute queries rather than recommend a source_model.

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

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

It gives clear context: use when you need a source_model for a set of items, and it explains edge behavior like null root_model with coverage for partial roots and root_hint override. It does not explicitly name sibling alternatives or state when not to use it, but the intended use is unambiguous.

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—and it does so thoroughly. It discloses id auto-allocation and upsert semantics, charset restrictions, cascade-on-delete stripping of entity references, preservation of zero-entity memories, lenient stale-tag filtering at retrieval time, and the exact return payload. This is far beyond what a naive 'save' description would provide.

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 long, but the length is justified by the polymorphic input and complex side effects. It is front-loaded with a clear purpose, then structured into short labeled sections and examples. Nearly every sentence carries distinct behavioral or semantic information needed for correct invocation.

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 nearly complete for a tool of this complexity: return values, id behavior, search integration, cascade deletion, and examples are all covered. The main omission is the `description` parameter, and there is no explicit pointer to `forget_memory` for cleanup, though the sibling list makes that relation inferable.

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

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

Schema description coverage is 0%, so the description must compensate. It richly explains `learning`, both forms of `linked_entities` (string list and SlayerQuery) with resolution rules, and `id` with allocation and upsert behavior. The one clear gap is the optional `description` property present in the schema but never mentioned in the description, leaving its semantics unexplained.

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

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

The description opens with a precise verb-resource pair: 'Save an agent memory' and immediately defines what a memory consists of (free-form note plus SLayer entities). It also differentiates the two memory forms by how they surface in search, which helps an agent distinguish this tool from read/search and forget siblings.

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 text gives strong contextual guidance: it explains cross-memory references, query-auto-extraction, and how memories appear in `search`'s `example_queries` vs `memories` lists. However, it never explicitly states when not to use this tool or names alternatives like `forget_memory` for deletion, so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full transparency burden, and it excels: it discloses channel preconditions, advanced_search/API-key fallback behavior, Reciprocal Rank Fusion, max_results capping, datasource scoping rules, ValueError conditions, cypher_filter restrictions, and warning emission. This level of behavioral disclosure is unusually complete.

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 long but well-structured: a front-loaded purpose, a bolded usage directive, numbered channel explanations, fusion/empty-input behavior, and an Args list. Each segment maps to a decision the agent must make or a behavior it should know. It is dense yet not padded.

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 complex tool with no annotations and a bare input schema, this description covers the essential surface: optional channels, installation/API-key prerequisites, datasource scoping, unknown-datasource errors, and cypher_filter limitations. Since an output schema exists, omitting detailed return-shape documentation is acceptable. The only minor gap is the undocumented `compact` parameter, already penalized under parameter semantics.

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

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

Schema description coverage is 0%, so the Args section is essential, and it adds real meaning to entities, query, question, datasource, max_results, and cypher_filter. However, the `compact` boolean parameter is never mentioned in the description, leaving its effect undocumented. The description compensates strongly for the bare schema but does not fully cover every parameter.

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

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

The opening sentence names a specific operation: three-channel semantic search over memories and canonical entities. The description further enumerates the channels, fusion method, and result capping, and distinguishes the tool from the `query` sibling with the instruction to call it before `query`. This is far more specific than a generic verb-plus-resource statement.

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

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

The description explicitly says 'Call this BEFORE `query`' and explains the exact input conditions under which each channel runs. It also documents empty-input behavior so an agent knows this tool still returns newest memories when no search terms are provided. This gives clear guidance on when to use the tool without requiring inference.

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

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

With no annotations provided, the description carries full behavioral disclosure and does so well: it explains the priority-list walk, first-match selection, AmbiguousModelError when no candidate matches, and empty-list clearing behavior.

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

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

The description is front-loaded with the core purpose, then uses a concrete ambiguous-model example to make the behavior intuitive. Every part—purpose, example, resolution rules, parameter semantics—earns its place 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?

For a simple one-parameter configuration tool, the description covers the scenario, prerequisites, error behavior, and clearing semantics. The output schema can handle return details, and no critical information is missing.

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

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

The schema only specifies 'priority' as an array of strings, so the description is essential. It adds ordering semantics (most-preferred first), the requirement that names already exist, and the empty-list clearing behavior.

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

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

States a specific verb and resource: 'Configure how SLayer disambiguates bare model names.' The description clearly distinguishes this from sibling tools like get_datasource_priority and list_datasources by focusing on the configuration/set 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?

Provides clear context for when this tool is needed—when bare model names exist in multiple datasources—and gives an actionable prerequisite (run list_datasources first). It does not explicitly contrast with get_datasource_priority, but the read/write pairing is implied by the sibling names.

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

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

With no annotations, the description carries the full burden and does so well: it explicitly states 'Read-only — does not modify storage', describes what the returned list contains, and discloses the behavior when data_source is omitted (validates all datasources concurrently and concatenates results).

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

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

The description is front-loaded with the core purpose, followed by return behavior, safety note, and parameter semantics. Every sentence earns its place; no filler 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?

For a tool with one optional parameter and an output schema, the description is complete: it explains the input, the output shape, the no-modification guarantee, and the default all-datasources behavior. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate. It fully explains the single parameter: 'Datasource name to validate', including the omission behavior and result concatenation. This adds meaning well beyond the raw 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?

States a specific verb and resource: 'Diff persisted SLayer models against the live database schema(s)'. It also clarifies the concrete output—a JSON list of pending delete operations—which distinguishes it from siblings like query, inspect_model, and delete_model.

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

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

The description gives clear context for when to use the tool: to validate persisted models against live schemas and preview required deletions. It does not explicitly name alternative tools or exclusions, but the purpose is specific enough that an agent can select it appropriately among the sibling tools.

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