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, the description carries the full burden. It discloses that query becomes source_queries, that query is mutually exclusive with other source parameters, and that columns are auto-introspected. It also provides deep guidance on row grain and join key selection, which is exceptionally transparent for a creation 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 long but well-organized, with examples and a structured parameter list. It front-loads the core purpose and then elaborates. The opening paragraph on row grain is dense but directly relevant to correct usage, so it 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?

Given the tool's complexity (9 params, two modes, mutual exclusivity), the description covers all necessary details: examples, parameter semantics, auto-introspection, and mutual exclusivity. An output schema exists, so return values are not needed. Nothing essential is missing for an agent to call this 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 fully. It does so by detailing every parameter: name conventions, types for columns and measures, mutual exclusivity, and the role of variables. Examples for both modes make the semantics concrete and actionable.

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: 'Create a new semantic model, either from a database table or from a query.' It immediately distinguishes two modes and provides concrete examples, making the tool's purpose unambiguous and clearly separated from siblings like edit_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 two usage modes with examples and notes that data_source comes from list_datasources, implying a prerequisite. However, it does not explicitly state when not to use this tool or contrast it with edit_model, though the purpose makes the primary usage 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?

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?

With no annotations provided, the description carries the full behavioral burden, and it does so thoroughly. It discloses mutation semantics, upsert-by-name behavior, mutual clearing between sql_table/sql/source_queries, refresh of cached columns, removal-before-upsert ordering, and the fact that join cardinality is descriptive metadata 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 long but earned: it covers 18 parameters, complex side effects, design guidance, and two examples in an organized, front-loaded structure. The purpose statement and key behavioral principles come first, followed by an Args list and 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?

For a complex 18-parameter mutation tool with zero schema descriptions and no annotations, the description is exceptionally complete. It covers parameter semantics, ordering, side effects, disambiguation rules, design principles, and usage examples; the presence of an output schema means return-value documentation is not required.

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. Every parameter is explained with real meaning: lookup rules for data_source, side effects for new_data_source, structure examples for columns/measures/aggregations/joins, and the exact clearing interactions among sql/sql_table/source_queries.

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,' and enumerates the full set of operations: update metadata, upsert columns/measures/aggregations/joins, manage filters, and remove entities. This clearly distinguishes it from siblings like create_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 context is clear: this is the tool for editing an existing model, and the examples demonstrate typical use cases. It does not explicitly state when to prefer a sibling tool or when not to use it, but the 'edit existing model' framing makes the intended use 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?

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 provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It reveals the no-fusion/no-ranking/no-cypher nature, batch error isolation with per-id error elements, canonical-id echoing, ignored parameter warnings, compact-mode behavior, and the fact that collection view only works for model/datasource. This goes well beyond typical descriptions.

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 covers three modes, eight parameters, kind-specific behavior, and error semantics. It is well-structured with clear section headers for single, collection, batch, and Args. Each sentence carries useful information; the ticket references and examples are compact and relevant. The front-loading of the core behavior makes it easy to scan.

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 (three modes, eight parameters, many kind-specific exceptions), the description leaves little to inference. It explains return shaping for markdown and JSON, error isolation, canonical resolution, parameter warnings, and which entities support collection view. The presence of an output schema means the description does not need to enumerate every render field, and it focuses on the behavioral and selection guidance an agent needs.

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 Args section is the only source of parameter meaning. It fully compensates by explaining reference forms (canonical, bare, join paths, memory), the required entity_type enum, the semantics of compact, format, num_rows, show_sql, sections, and descriptions_max_chars, including which parameters are ignored for which kinds. Every parameter is given practical, non-obvious 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 leads with a precise statement: Inspect exactly one entity by reference and kind, a homogeneous batch when reference is a list, or a whole collection when reference is omitted. It also distinguishes itself from siblings by naming search as the alternative for in-context lookup and noting that it subsumes models_summary and list_datasources. This is a model of clear purpose and 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 explicitly states when to use the tool vs. alternatives: 'Use search instead when you want an entity surfaced in context (with related memories and ranked neighbours).' It also provides concrete guidance for collection mode, batch mode, and warns which entity types support collection. The advice to inspect columns before using them in filters/joins adds valuable use-context instructions.

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 provided, the description carries the full behavioral burden and does so exhaustively: default 20-row truncation, automatic WHERE/HAVING/post-aggregation filter routing, broadcast warnings for non-attributable dimensions, topological stage ordering, dotted-path flattening, and precedence rules for variables. It also discloses debug behaviors (show_sql, dry_run, explain) and verification 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 long, but every section earns its place for a tool of this complexity: purpose and prerequisites are front-loaded, and bold headers with bullet lists make the expression rules, argument forms, filters, and verification steps scannable. The included example concretizes the abstract spec 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?

Given the tool's complexity, an output schema, and zero annotation coverage, the description is essentially complete: it covers preconditions, input forms, expression syntax, filter construction, stage semantics, debug options, output format, row caps, and a verification protocol. Nothing an agent must know to invoke this tool safely and correctly is left undocumented.

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% for top-level parameters, and the description fully compensates by documenting all five top-level siblings (variables, show_sql, dry_run, explain, format) with precedence and behavior, plus the three forms of the query argument in depth. It adds meaning far beyond the schema, including the expression language, gran() forms, and per-field clarification of query-object semantics.

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?

"Query data from a semantic model" states a specific verb and resource, and the opening lines position this tool as the execution step after inspect and search, naming sibling tools explicitly. The three query argument forms and the worked example further pin down exactly what this tool does versus siblings like inspect_model or search.

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 to call inspect(...) first and search(...) before finalizing a query, giving an unambiguous workflow. It also states when to use multi-stage lists versus single-query nesting, and warns against using limit to trim plain lists — clear when-to-use and when-not-to-use guidance.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses directional LEFT joins, bidirectional INNER joins, min-hop optimization, root_hint override semantics, the warning when the hint is ignored, and the null-root/coverage fallback. This goes well beyond a basic 'recommends a root' summary.

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 methodically covers behavior, edge cases, usage timing, and parameters. Every section earns its place; the Args section adds semantic value beyond the schema rather than repeating it.

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 join-graph tool with 0% schema parameter coverage, the description is complete: it covers when to use it, all parameter semantics, key edge cases, output examples, and interaction with sibling tools. The existing output schema handles detailed return-structure documentation, so nothing essential 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 — and it does. items gets concrete spellings and examples, data_source gets scope and single-datasource constraints, root_hint gets override behavior and resolution order, and format gets its allowed values and default.

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 statement: it recommends a root model for a set of items and returns join-qualified reference paths. It also distinguishes itself from schema-browsing siblings by explicitly saying it is not a schema browser and pointing to search/inspect for exploration.

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 states when to call the tool: once the item list is final, not during exploration. It also names alternatives (search/inspect) and explains the fallback behavior when no single root reaches every item, which helps an agent decide whether to split the request.

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 delivers extensively. It discloses upsert semantics, id auto-allocation rules, charset restrictions, cascade-on-delete behavior, lenient stale-tag filtering, and non-fatal resolution warnings. This is far beyond what an agent could infer from the schema alone.

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-organized, with a leading one-sentence summary followed by clearly scoped sections and practical examples. The length is justified by the absence of annotations and schema descriptions, though a few sections could be tightened without losing 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?

For a complex tool with no annotations and rich schema, the description covers purpose, input forms, id behavior, deletion side effects, search integration, and return values. The only notable omission is the optional description parameter, but overall the agent has everything needed to invoke the tool correctly and anticipate consequences.

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 thoroughly explains learning, linked_entities, and id, including accepted formats, edge cases, and examples. However, the schema also exposes a 'description' parameter that the description never mentions, leaving one of the four parameters undocumented.

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 and resource: 'Save an agent memory: a free-form note plus the SLayer entities it concerns.' It distinguishes the tool from siblings like search and forget_memory, and even explains where saved memories surface in search's results, making its role 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 provides strong context for when to save a memory, including two distinct input modes (entity list vs SlayerQuery) and explains that query-based memories appear in search's example_queries list. It does not explicitly name alternatives or state when not to use this tool, but the save-versus-search/forget relationship is clear from 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 and does so thoroughly: it discloses empty-input behavior, the warning-on-skip behavior for the dense channel, `ValueError` on unknown datasource, RRF fusion, and the context-cache cost of `compact=False`. This goes well 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?

The description is long but densely packed and well-structured: a top-line purpose, ordering instruction, channel breakdown, fusion/empty-input behavior, then parameter docs. Every sentence carries operational value for a complex 7-parameter tool, so the length is earned.

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, no annotations, and an output schema present, the description covers all invocation concerns: channel preconditions, result fusion, error cases, scoping semantics, and cypher_filter limitations. An agent has enough to call this correctly in varied 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 0%, so the description must explain every parameter. It provides detailed semantics for `entities`, `query`, `question`, `datasource`, `max_results`, and `cypher_filter`, and explains `compact` in prose. This fully compensates for the schema's lack of 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 opening line names a specific operation and resource: 'three-channel semantic search over memories + canonical entities.' It also positions the tool against siblings by stating it is discovery-level and that full bodies should be read via `inspect`, making its role 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 explicitly instructs agents to call this before `query`, tells them to use `inspect` for details, warns against broad `compact=False`, and explains when each channel runs. It also gives concrete cypher_filter guidance, leaving little room for mis-selection.

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.