Auto Ontology MCP

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

Goes meaningfully beyond annotations: it clarifies that the stored connection is always read-only (reconciling the readOnlyHint=false write semantics), discloses the default schema scan side effect, and warns against fabricating credentials. Missing is what happens on duplicate registration or how long a scan of a large database takes.

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

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

Two sentences, zero filler, with the core action and the default scan behavior front-loaded before the usage restriction. Every clause carries information an agent needs.

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?

A mutation tool with annotations, a full output schema, and complete parameter docs — the description covers the behavior an agent must know to call it safely. Only edge cases like duplicate names or long-running scans are absent.

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

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

Schema coverage is 100%, so each of the five parameters is already fully documented, including URL syntax examples and the default-true scan flag. The description only reiterates the URL requirement and the scan default, adding no semantics beyond the schema.

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

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

Specific verb and resource: 'Register a database' with the added default behavior of scanning it, plus a note that the resulting connection is read-only. That distinguishes it reasonably from scan_datasource, though the sibling is never named explicitly.

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?

'Use only when the user gives you a connection URL; never invent credentials' is a clear inclusion condition plus a hard exclusion. It stops short of naming alternatives or stating what to do if the datasource already exists, deferring that to the idempotent hint.

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

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

Annotations already mark this as a non-read-only but non-destructive, idempotent write. The description adds genuine behavior beyond that: validation is all-or-nothing (nothing is written if any record is invalid) and every problem is reported back. It does not cover permissions or how partial conflicts interact with the batch, keeping it short of a 5.

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

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

Three tight sentences, each doing a distinct job: what to store, how validation behaves, how duplicates are handled. Front-loaded with purpose and free of filler, though the parenthetical example list runs slightly long.

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

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

With full schema coverage, an output schema and annotations in place, the description only needs to carry the write semantics, which it does well (atomic validation, dedup/upsert behavior). The gap is the relationship to edit_records and what a failed validation response looks like, which are minor given 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 100%, so entity, source, records, on_conflict and create_missing_refs are all documented in the schema itself. The description reinforces the conflict/dedup semantics of on_conflict and key matching but adds no syntax or value-level meaning beyond the schema. Baseline 3 applies.

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

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

The description opens with a specific verb and resource: store facts extracted from user-shared artifacts (receipts, statements, notes, logs). That is far more concrete than the tool name alone. It does not name a sibling alternative such as edit_records, so an agent must infer the boundary between adding and editing.

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 implies the triggering context (after extracting facts from something the user shared) and clarifies that repeated calls are safe because matches update or are skipped. However it gives no explicit when-not guidance and never points to edit_records as the alternative for correcting existing rows.

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

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

Annotations already declare this is a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower, yet the description still adds real behavior: it is cheap, it enumerates the four possible verdicts, and it returns per-entity best matches despite no match being a failure signal. The instruction not to substitute a similar measure when material coverage is missing is important behavioral guidance an agent would not otherwise know.

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

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

Three sentences, front-loaded with the core framing ("Cheap pre-flight") and the return shape before the operational caveat. Nothing is padded, though the verdict enumeration could arguably be left to the output schema.

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

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

With an output schema present, return values need not be re-explained, and annotations cover the safety profile; the description supplies the conceptual model and the failure-mode guidance. The one gap is that its relationship to the similarly named check_readiness sibling is left for the agent to guess.

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

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

Schema description coverage is 100%, including a detailed extraction recipe for `entities` and the optional-datasource note, so the schema carries the parameter burden. The description adds no parameter-level detail beyond implying that the question's entities are what gets checked. Baseline 3 is appropriate.

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

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

The description gives a specific verb and resource: it checks whether the ontology covers every entity in a question, and names the outputs (coverage, verdict, best matches). An agent can tell this is a coverage pre-flight rather than a data query. It stops short of explicitly contrasting itself with the sibling check_readiness, which reads like an adjacent pre-flight tool.

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

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

"Cheap pre-flight" implies it should run before heavier operations, and the last sentence tells the agent what to do when coverage fails. However, it never states when to use this versus check_readiness or get_query_context, and gives no explicit exclusions. Usage is inferable rather than specified.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing the aggregate scope (all datasources, not one) and that each row carries both a runnability signal and a modeling-completeness signal plus a recommended next action.

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

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

Two sentences with no filler. The action-oriented instruction is front-loaded before the description of returned content, which is the right order for an agent scanning the text.

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

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

With zero parameters, full annotation coverage, and an output schema that documents the return shape, the description needs only to explain intent and scope, which it does. Minor gap: "what to do next" is unexplained and the description doesn't note whether the list can be large or how results are ordered.

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 defines zero parameters, so there is nothing for the description to clarify; baseline 4 applies. The description correctly implies a no-argument call by describing filtering-free enumeration of every datasource.

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?

"Lists every datasource" gives a concrete verb and resource, and the qualifiers (whether SQL can run, how much is modeled, what to do next) define the exact payload. The opening "Start here" frames it as the orientation/status tool, which separates it from point queries like check_answerable, validate_sql, or get_modeling_worklist in the sibling list.

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?

"Start here" is an explicit onboarding instruction that tells an agent to invoke this before other tools. It does not name when to skip it or which sibling to use after a specific readiness result, so the routing is clear on entry but not on exit.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description corroborates both (delete, and keys causing 're-adding updates instead of duplicating') rather than contradicting them. It adds real policy beyond the annotations: reserved id/_source_id/_evidence fields, ref columns materializing as relationships, 'Never invent values,' and 'do not certify on your own' — though it never warns that deletion with force is irreversible.

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 sentence is well front-loaded, but the six numbered points are largely a general knowledge-modeling manifesto: point 3 is about concepts (save_concept's job) and point 4's per-record locator/evidence advice belongs to add_records. Roughly half the text does not earn its place in this tool's definition.

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, destructive, idempotent schema with full coverage and an output schema, the description covers naming, typing, keys, and provenance well enough to call correctly. The gap is the phantom `source` parameter and the missing note that force-delete is unrecoverable.

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

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

Schema coverage is 100%, so baseline is 3, and the description does add value on keys (upsert semantics) and ref:<Entity> column types. But it also tells the agent to 'pass source={title, kind, uri, ...}' and to supply per-record _locator and _evidence — none of which are parameters of this tool, which has additionalProperties: false, so following that instruction would produce a call error.

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?

Opens with a specific triad of operations — create an entity (a Term with its own table), add columns, delete it — naming the concrete resource and its physical form. It implicitly separates itself from save_concept (which holds meaning, not countable facts) and from add_records, so an agent can pick the right tool without reading the schema.

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

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

Explicitly routes the agent to a sibling first: 'Reuse before you create: search_ontology for the thing first,' and gives the entity-vs-concept decision rule. It stops short of saying when to call update_term instead of define_entity, or when a new column should become a separate entity, so one selection boundary is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful fact that the payload includes term bindings, attribute mappings, relationships and SQL attributes. It says nothing about behavior when the table or datasource is missing, or how the single-datasource default is resolved.

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?

It is a single short sentence with no wasted words, but it is a fragment that leads with the object rather than the action, so it is under-specified rather than efficient. A leading verb would have cost nothing.

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?

An output schema exists, so the description need not explain return values, and the safety profile comes from annotations. What is missing is invocation context: no indication of when this lookup is the right call versus its many siblings, which is the main risk of misuse here.

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

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

Schema description coverage is 100% for both parameters, including the schema-qualification note and the optional-datasource default, so the schema carries the semantics. The description adds no interpretation of 'table' or 'datasource' beyond that, which is the expected baseline case.

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 text is a noun-phrase inventory of the resource ("A physical table with its Terms, columns ..., relationships and SQL attributes") rather than a verb+object statement of what the tool does. It does tell an agent what content the result contains, which helps distinguish it from get_term or list_relationships, but the agent has to infer 'describe' from the title alone.

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?

There is no when-to-use guidance and no named alternative, despite many plausible siblings (get_source, get_term, search_ontology, list_relationships, get_query_context). Nothing states whether to call this before writing SQL, or how it differs from fetching a source or searching the ontology.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value on top: referential-integrity refusal semantics and a human-confirmation requirement. It omits one notable side effect — that passing a source object registers a new source — which is only visible in the schema.

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

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

Three short sentences, zero filler, with the core action front-loaded and the destructive caveat immediately after. Nothing could be removed without losing information.

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

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

An output schema exists, so return values need not be described, and full schema coverage carries parameter detail. The remaining gap is explaining the update-vs-delete asymmetry (values apply only to update, source registration is a side effect), which an agent must piece together itself.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only echoes "by id"; it adds no meaning for entity, action, values, or the source-registration branch beyond what the schema already documents.

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?

"Correct or delete records by id" names two specific verbs, the resource (records) and the addressing key (id), which separates it from add_records or update_term. It never names a sibling explicitly, so the differentiation is inferable rather than stated.

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 one concrete usage rule — confirm with the user before deleting — plus the failure condition that deleting a referenced record is refused. It says nothing about when to prefer this over add_records, update_term, or define_entity, and gives no guidance on when an update should be routed elsewhere.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile needs no restating. The description adds useful context by indicating this returns the complete layer in a single document (not a filtered subset) and that it is serialized as YAML/JSON, but it says nothing about size limits, permission requirements, or behavior when the datasource argument is omitted despite multiple datasources being registered.

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

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

One dense sentence that front-loads the resource and scope before the parenthetical inventory of included sections and the closing use case. Every element earns its place, with only minor overhead from the long parenthetical list; the phrase is a noun fragment rather than an explicit verb statement, which is a small structural weakness.

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

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

With an output schema present and only two optional parameters at full schema coverage, the description carries little burden and covers the main open questions: what is exported, in what format, and for what purpose. The only meaningful gap is what happens when 'datasource' is null and several datasources exist, which neither the description nor schema resolves.

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

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

Schema description coverage is 100%, with both the 'format' enum and the optional 'datasource' parameter already documented in the schema, including the single-datasource default behavior. The description confirms that the document covers exactly one datasource and that formats are YAML/JSON, but adds no syntax or format-selection guidance beyond what the schema provides, so baseline 3 applies.

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

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

The description names a specific resource and scope: 'the whole semantic layer of a datasource as one YAML/JSON document', and enumerates what is included (Terms, column mappings, SQL attributes, relationships, glossary, example queries). This clearly separates it from retrieval tools like get_term or search_ontology, though it never explicitly names export_wiki or import_ontology as the adjacent alternatives.

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

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

The trailing clause 'for review or version control' implies the intended use case, so an agent can infer this is a full-dump/backup operation rather than a targeted lookup. However, there is no explicit when-not guidance and no routing statement telling the agent to prefer export_wiki for wiki output or import_ontology for the reverse operation.

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

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

Annotations only say readOnlyHint=false, idempotentHint=true, destructiveHint=false; the description goes well beyond them by naming the exact output path (~/.auto-ontology-mcp/wiki/<datasource>), spelling out that re-export replaces *only* generated files (so user edits elsewhere survive), and warning that the export is one-way with no read-back. These are exactly the operational facts an agent needs before writing to disk.

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?

Front-loaded with what gets produced, then path, then overwrite semantics, then the one-way caveat — a logical order with no filler sentences. The opening sentence is dense with parenthetical and inline-list detail, which costs a little readability but not clarity.

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

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

For a single-optional-parameter export tool with an output schema (so return values need no explanation) and annotations covering safety, the description covers everything material: what is emitted, where it lands, what gets overwritten, and the non-round-trip limitation. Nothing an agent needs in order 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 coverage is 100% and the single optional 'datasource' parameter is already documented, so the baseline is 3. The description adds a little: it names <datasource> as the path segment and implies the default datasource is used when unspecified, which matches the schema's null default without contradicting it. Marginal but real added meaning.

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 concrete verb (write/export) and a concrete artifact set: one markdown page per Term with synonyms as aliases and relations as [[links]], one per source, an index.md and a log.md. The Obsidian-vault framing plus the one-way-view note separates it from export_ontology and import_ontology among the siblings without needing their schemas.

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

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

It supplies useful operating context — the ontology is exported 'by default', the target folder, and that re-exporting replaces generated pages only — but never states when an agent should choose this over export_ontology, nor any preconditions (e.g. must the datasource be scanned first?). Usage is implied rather than directed.

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

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

Annotations already declare this a non-destructive, closed-world read, so the safety profile is covered. The description adds genuine value by saying the return is the FULL text of exactly one document (as opposed to a summary or a collection) and by enumerating the document shapes. It says nothing about behavior on a missing or malformed id, or about document size limits.

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

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

A single compact sentence with the core claim ('full text of one ontology document') front-loaded and the document-type enumeration trailing as qualification. No filler, though the parenthetical list is slightly dense for one sentence.

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

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

With an output schema present, the description need not explain return values, and the annotations cover safety. For a one-parameter read tool the description is nearly sufficient; the only real omission is routedness versus the closely related get_term and describe_table siblings.

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

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

Schema description coverage is 100% and the single id parameter is fully documented with a concrete example format ('term:term_ab12'). The description adds no additional semantics about the id beyond what the schema already supplies, so the baseline 3 applies.

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

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

States a clear verb (full text retrieval) and a precise resource (one ontology document), and enumerates what a document can be: a Term with its attributes, SQL attributes and relationships, or a table. This differentiates it from search-style siblings, though the generic name 'fetch' does not on its own, and it does not name get_term or describe_table as distinct alternatives.

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

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

Usage is only implied: the schema note that the id is 'returned by search' suggests the search-then-fetch workflow, and 'full text of one document' implies it is for expanding a single result rather than listing. There is no explicit statement of when to prefer this over get_term or describe_table, nor any exclusion or prerequisite stated in the description itself.

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

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

Annotations already establish that this is a safe, read-only, closed-world operation, so the description is free to add behavioral detail — and it does: the path is limited to 'accepted' relationships, fan-out is warned about, and ambiguous roles (billing vs delivery city) are surfaced. It stops short of saying what happens when no path is found.

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

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

One compact sentence with the core object front-loaded and no filler. The trailing list of outputs is slightly dense but each item conveys a distinct capability.

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

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

The tool is simple (3 params, 2 required) and an output schema exists, so return values needn't be spelled out. The remaining gap is failure behavior — no path exists, or multiple datasources registered — which the datasource parameter's optionality hints at but the description never addresses.

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

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

Schema coverage is 100%, with source/target/datasource each documented, so the baseline is 3. The description reinforces that source/target accept either a Term or a table name, but adds no syntax, naming, or datasource-selection guidance beyond the schema.

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

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

States a specific operation (shortest chain of accepted relationships) on a specific resource (two Terms or tables) and enumerates the payload (ON conditions, FROM/JOIN clause). This is clearly distinct from siblings like list_relationships or set_relationship, which enumerate or modify rather than compute a path.

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 usage context (you need a join between two entities and want a ready-made clause) but never states when to prefer it over list_relationships or get_query_context, nor when it is inappropriate (e.g. no accepted relationship exists).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real value by disclosing the shape of the returned context and the loop-termination signal ('remaining is 0'). It does not discuss ordering guarantees, whether the worklist can change between calls, or datasource-scoping 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?

Three tight sentences, front-loaded with the resource and its payload before the workflow instruction. The dense list of column metadata is somewhat run-on but every element earns its place; no filler.

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

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

With an output schema present, annotations covering safety, and 100% parameter coverage, the description only needs to explain the workflow and handoff, which it does fully. An agent knows what it gets back, what to do next, and when to stop.

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

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

Schema description coverage is 100%, so limit, tables, and datasource are already documented in the schema. The description echoes the 'tables' semantics ('instead of the next pending ones') but says nothing about limit or datasource defaults or interactions. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description names a specific resource and scope ('next tables that still need business Terms') and enumerates the payload (candidate columns with types, sample values, uniqueness, formats, foreign keys with their Terms, modeling rules). It is clearly distinct from siblings like describe_table or get_term, and it names the downstream tool save_table_terms.

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

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

It gives an explicit workflow: call this, then call save_table_terms once per table, and repeat until remaining is 0. It also implicitly covers the re-modeling case via the 'tables' parameter. There is no explicit 'when not to use' or named alternative for other listing needs, which keeps it below a 5.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the bar is lower. The description adds that the join path comes with a ready FROM/JOIN clause and role notes and that examples are 'verified', which is modestly useful context about output quality. It says nothing about failure modes, what happens with unknown terms, or datasource resolution.

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?

It is a single dense sentence with no filler, and the payoff ('Everything needed to write the SQL') is front-loaded before the colon-led enumeration. The list is long but each item is a distinct artifact, so nothing obviously wastes space.

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?

An output schema exists, so the description does not need to enumerate return contents, yet it does so at length while leaving preconditions unaddressed. For a bundled context-fetching tool, an agent would still benefit from knowing whether a missing or ambiguous term degrades the result and whether a datasource must be scanned first. It is adequate but leaves real gaps.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already explains terms, question and datasource. The description hints at the relationship between terms and the generated join clause and between the question and verified example queries, adding slight meaning. It does not clarify term-resolution behavior (names vs synonyms vs ids) or whether multiple terms must be related.

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

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

The description names the specific resource it assembles (qualified tables, mapped columns with sample values, join path, verified examples, glossary, dialect rules) and frames it as the complete input for writing SQL, which distinguishes it from narrower siblings such as find_join_path or lookup_values. It leans on a noun phrase rather than a verb+resource pairing, but the content is concrete enough that an agent knows exactly what it gets.

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 only implied by the phrase 'Everything needed to write the SQL', which suggests calling it before authoring a query. It never says when to prefer it over siblings like describe_table, get_term, find_join_path or lookup_values, nor what to do if the returned context is insufficient. No exclusions or prerequisites are 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the useful scope detail that the result is an aggregate (source plus everything derived from it), but says nothing about what happens when the id or title fragment matches nothing, or whether partial-title matches can be ambiguous.

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

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

Two sentences, no filler, and the payload contents are listed up front before the citation use case. The opening clause ('One source with its summary and content') is slightly awkward as a fragment but costs almost nothing.

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

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

The tool is simple: one required parameter, full schema coverage, an output schema, and complete annotations. The description covers purpose, payload shape, and one usage scenario, leaving only edge-case behavior (no match, ambiguous title match) unstated, which is a minor gap at this complexity.

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

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

Schema description coverage is 100%, and the single 'source' parameter is documented in the schema as an id or part of a title. The description adds no further meaning about the id-vs-title resolution or match behavior, so the baseline of 3 applies.

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

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

The description names the resource ('one source') and enumerates exactly what comes back: summary, content, records per entity, concepts and relations. That content inventory distinguishes it from generic retrieval siblings like search/fetch, though it never names those siblings explicitly.

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?

'Use it to cite where an answer came from' gives one concrete usage context, which is more than nothing. However, there is no when-not guidance and no routing advice relative to search, fetch, or get_term, which an agent could plausibly confuse it with when it only has a partial title.

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

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

The annotations already declare this is a safe, read-only, closed-world operation. The description usefully adds that the returned term includes mapped columns with sample values and formats, plus related Terms with join conditions and multiplicity, but it does not mention lookup failure behavior, datasource ambiguity, or other operational caveats.

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 compact sentence with no filler, and it front-loads the key scope ('One Term'). The fragmentary noun-phrase style is slightly less readable than a complete sentence, but every listed detail is informative.

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 read operation with annotations covering safety, a fully described two-parameter schema, and an output schema, the description is largely complete. It tells the agent what details are available for a term, though it omits usage routing and edge-case behavior.

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

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

Schema description coverage is 100%, so the schema fully documents that 'term' accepts a name, synonym, or id, and that 'datasource' is optional when only one datasource is registered. The description adds no parameter meaning beyond the schema, which is the expected baseline when the schema carries the 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 clearly identifies the resource as a single Term and enumerates the detailed information returned: definition, status, synonyms, mapped columns, SQL attributes, and related Terms. It implicitly contrasts with the sibling list_terms by saying 'One Term', but it does not use an explicit retrieval verb or name the alternative tool.

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

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

The description gives no explicit when-to-use guidance, no prerequisites, and no alternatives. The singular 'One Term' suggests it is for fetching a specific term rather than listing terms, but the agent must infer this without any stated comparison to list_terms or search_ontology.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds a genuinely useful behavioral detail — matching tables and columns by name — which hints at how the document is reconciled against the scan. It does not say what happens on unmatched or renamed objects, whether existing terms are overwritten, or whether it partially applies on error.

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

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

One sentence with no filler, and the core action is front-loaded. The trailing parenthetical carries real information rather than noise, though the sentence is dense enough that the matching semantics are easy to miss.

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

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

With an output schema, full schema coverage, and rich annotations, the description need not explain returns or safety. However, for a mutation that applies an exported document over a scanned datasource, the description omits the conflict/overwrite outcome and the preconditions (scanned datasource, single-datasource default), which are the details an agent most 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?

Schema description coverage is 100% and the datasource parameter's optionality is documented in the schema itself. The description adds only the indirect note that the document should match by name, which does not materially extend parameter meaning beyond the schema; baseline 3 applies.

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

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

States a specific verb ('Apply') and resource ('an exported document') against a target ('a scanned datasource'), and the mention of 'exported document' implicitly ties it to the export_ontology sibling as its inverse. It is clear what the tool does, though it never explicitly contrasts itself with export_ontology.

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 only implied: the document must have been produced by export_ontology and the target must already be a scanned datasource. There is no explicit when-to-use/when-not guidance or statement of prerequisites (e.g. datasource must be scanned first), leaving the agent to infer the workflow.

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 readOnlyHint=true and destructiveHint=false already declared, the safety profile is covered by annotations. The description does add genuinely non-structured context — that evidence can be declared, inferred by name/value containment, or manual, and that role disambiguation and unlinked identifier columns are surfaced — but says nothing about volume, ordering, or scoping behavior of the listing.

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

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

Two sentences, both carrying information: the first enumerates returned content categories, the second points at the mutation counterpart. The parenthetical evidence taxonomy is dense but earns its place; the only weakness is that the resource is front-loaded instead of the verb.

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?

An output schema exists, so return-value explanation is unnecessary, and the description covers the meaningful content categories of the response. What is missing is modest: guidance on default scope (only proposed relationships), and how this listing relates to join-path or worklist tools.

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

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

Schema description coverage is 100% and all three parameters are documented in the schema, so the baseline is 3. The phrase "proposed ones" faintly echoes the default status filter, but the description adds no syntax, format, or interaction detail beyond what the schema already states.

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

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

The description names the resource precisely — joins between tables, their evidence provenance (declared, inferred, manual), roles for multi-column joins, and orphan identifier columns — so an agent knows exactly what comes back. The action verb is only implied ("Joins between tables..."), carried by the name/title rather than the description text, which keeps it just short of a 5.

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

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

It routes one case explicitly: "Review proposed ones with set_relationship," which tells the agent this is the read side and set_relationship the write side. It gives no guidance on when to prefer this over related siblings such as find_join_path or get_modeling_worklist, nor any condition for choosing a status value.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that: the payload contents and the fact that it surfaces still-empty concepts, which is behavioral information an agent would not get from the annotations.

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

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

Two sentences, no filler, and the payload description is front-loaded ahead of the usage instruction. Every clause carries information.

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

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

An output schema exists, so return values need not be spelled out, and the description still summarizes them. For a read-only, fully documented list tool this is nearly complete; only paging behavior and the optional-datasource case are left entirely to the 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 description coverage is 100%, with kind, status, limit, offset and datasource all documented in the schema itself. The description adds no filtering or paging semantics beyond that, so the baseline 3 applies.

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

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

States a specific resource (the datasource's Term index) and enumerates exactly what each entry carries: one-line definition, status, synonyms, record and relation counts, and empty concepts. This is clearly distinguishable from get_term (single Term) and search_ontology (search) among the 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?

Gives an explicit when-to-use rule: read it before adding knowledge so existing Terms are reused rather than duplicated. It does not name a specific alternative tool or state when not to use it, which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the agent knows the safety profile. The description adds the behavioral purpose of grounding literals but says nothing about whether values are distinct, how they are ranked, or how limit truncation behaves. With annotations and an output schema covering most of the surface, a 3 is appropriate.

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

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

A single sentence that front-loads what the tool returns and follows with the use case and concrete examples. Every clause earns its place with no filler.

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

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

Output schema, complete parameter docs, and safety annotations are all present, so the description only needs to convey intent and usage, which it does. The one gap is that it does not mention the common-value ordering or the multi-datasource requirement, both of which an agent would need to consult the schema for.

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

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

Schema coverage is 100%, so all four parameters are fully documented in the schema, including the 'table.column' format and the contains/limit behavior. The description adds intent (grounding filters) but no additional format or constraint detail beyond the schema, so it sits at the baseline.

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

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

The description states a specific resource (real values stored in a column) and its purpose (grounding literal filters). The examples ('Pennsylvania', product name, status code) make the output concrete. It does not explicitly distinguish itself from siblings like describe_table or get_term, which also describe column contents, so it falls short of a 5.

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

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

It gives clear temporal guidance: call this before writing literals into SQL. That establishes when to use it. There is no explicit when-not guidance or named alternatives (e.g., use describe_table to get the column type instead), which keeps it at 4.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the event taxonomy and the newest-first ordering, which is genuinely useful, but it doesn't define the scope of "recently" (time window, workspace-wide vs. object-scoped) or whether entries can be truncated.

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

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

One sentence with no padding, and the ordering constraint is placed at the end where it reads naturally. The leading "The log:" fragment is slightly awkward but does front-load the concept.

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

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

The tool is simple (zero required params) and an output schema exists, so return values need no explanation. However, the undefined scope of "recently" — no timeframe, no indication of whether the log spans the whole ontology or a single resource — is a real gap for an agent deciding whether this answers its question.

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

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

Schema coverage is 100% and the single limit parameter is documented in-schema, so the baseline is 3. The description's "newest first" restates what the schema already says about ordering and adds no new meaning about bounds or defaults.

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

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

The description names the resource (a change log) and enumerates the event types it covers — added, changed, certified, deleted — plus the ordering, which is enough to tell it apart from siblings like search or get_term. The phrasing "The log:" is fragmentary rather than a clean verb+resource statement, but the intent is unambiguous.

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

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

There is no when-to-use guidance: nothing says whether to reach for this versus search, get_term, or check_readiness when investigating recent activity, and no prerequisites or exclusions are stated. Usage is only inferable from the word "log."

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with concrete behavior: the connection itself is read-only and writes, DDL and multiple statements are refused. It also discloses truncation behavior and instructs the agent to present the SQL and flag truncation, though it duplicates the shape of the response that the output schema already defines.

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

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

Three tight sentences: capability and return shape first, hard constraints second, agent-facing presentation instruction last. Nothing is wasted, and the most decision-relevant fact (read-only execution) 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?

With annotations, a full-coverage schema and an output schema, the description covers what an agent needs: what gets executed, what is refused, and how to report truncated results. It stops short of covering timeouts, result-size limits, or the validate-then-run workflow implied by the validate_sql sibling, which would make it complete for a multi-step SQL agent.

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

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

Schema description coverage is 100%, so all four parameters (sql, max_rows, question, datasource) are already documented in the schema, establishing a baseline of 3. The description adds only a small amount of meaning beyond that, mainly the link between max_rows and the truncated flag, without covering dialect constraints or the provenance role of 'question' beyond what the schema says.

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 gives a specific verb ('Execute') and resource ('a read-only query') plus the exact result shape (columns, rows, row_count, truncated, Terms, warnings), which is far more than a restatement of the name. It does not explicitly position itself against the nearby validate_sql or check_answerable siblings, leaving the agent to infer that this is the execution step rather than the validation step.

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 clearly bounds usage by refusing writes, DDL and multiple statements, which is useful when-to-use context. However, there is no explicit guidance on when to call validate_sql first, when to prefer lookup_values or check_answerable, or how to handle a query that is rejected, so the alternative-selection guidance is only implied.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=false. The description adds genuinely new behavioral context: this is an upsert, it implicitly creates empty concepts for missing relation targets, and it applies to entity Terms. It does not spell out overwrite semantics for the existing body, though the schema parameter text partly covers that.

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

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

Three sentences, front-loaded with the core create-or-update action, then scope, then side effects. No filler, though the sentence about empty concepts could be folded into the first for even tighter packaging.

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

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

With an output schema present, 100% schema description coverage, and rich annotations, the remaining burden on the description is small, and it covers the non-obvious parts: upsert semantics and implicit Term creation. Nothing essential for correct invocation 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 100%, so the schema already documents all 12 parameters in detail. The description only adds a structural framing (definition, markdown body, typed relations) rather than parameter-level meaning, which is the expected baseline when the schema does the heavy lifting.

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

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

The description gives a specific verb pattern (create or update) and a resource (a concept: Term + definition + markdown body + typed relations), which clearly separates it from note- or record-oriented siblings. It also clarifies that entity Terms can be documented. It stops short of naming the nearest alternatives (update_term, save_glossary, define_entity) directly, so an agent must infer the boundary.

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 only implied: the upsert framing and the statement that non-existent targets 'become empty concepts to fill in later' tell the agent this is a write that can also stub out missing Terms. There is no explicit when-to-use/when-not-to-use guidance versus update_term or save_glossary, and no prerequisite conditions are 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?

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the write-safety profile is covered. The description adds genuine context beyond that by explaining the downstream effect: verified examples feed get_query_context and get mined by suggest_sql_attributes, which tells an agent why the stored pair's accuracy matters.

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

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

Two tightly written sentences, with the core action and its correctness precondition front-loaded and the downstream consequences following. Nothing is redundant with the title or schema.

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

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

With four fully documented parameters, complete annotations, and an output schema, the description covers what an agent needs to decide to call it. The only small gap is that the idempotent behavior (what happens on re-saving an identical pair) is not mentioned.

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

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

Schema description coverage is 100%, and every field (question, sql, note, datasource) is documented in the schema itself. The description adds no syntax, format, or constraint detail beyond that, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Store a question and SQL pair') along with the qualification that it must be user-confirmed as correct. It also names two downstream consumers, which distinguishes this save tool from siblings like get_context or suggest_sql_attributes that only read or mine examples.

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 condition for use is clear: only save pairs the user has confirmed as correct, which implicitly excludes speculative or unvalidated SQL. There is no explicit 'do not use when' clause or named alternative (e.g., validate_sql for unverified queries), so it stops short of full alternative routing.

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

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

Annotations already supply the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the description only needs to add context. It does add something useful — that entries are returned with query context and are searched like Terms — but it never mentions that the tool also deletes entries via the `delete` parameter, which is the one behavior an agent most needs warned about on a write 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?

Two short sentences with no padding, and the resource definition is front-loaded with a concrete example. The second sentence about query context is slightly indirect but still earns its place by linking the glossary to retrieval behavior.

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?

An output schema exists, so return values need not be explained, and the schema fully documents parameters. However, for a four-parameter mutation tool that can also delete entries and choose between datasource and global scope, the description leaves the destructive and scoping decisions entirely to the schema, which is adequate but not complete.

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

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

Schema description coverage is 100% and each parameter (delete, entries, datasource, global_scope) is documented in the schema itself, so the baseline is 3. The description adds only the domain framing of what a glossary entry is, not any additional semantics about scoping or update-versus-create 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?

The resource is clearly named (a glossary of abbreviations and internal jargon) with a concrete example (MRR → monthly recurring revenue), but the verb "Maintain" is vague and does not distinguish this from siblings such as update_term, save_concept, or list_terms. An agent can infer it is a glossary-writing tool from the name, but the description itself does not sharpen that distinction.

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?

There is no explicit when-to-use guidance: nothing tells the agent when to choose save_glossary over update_term or save_concept, nor when to scope an entry to a datasource versus using global_scope. The line "searched like Terms" hints at a relationship with the Terms tooling but stops short of an actionable rule.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: the expression is executed read-only against the live database before persisting, and a broken one is rejected with the error — an agent needs to know saves can fail for SQL validity reasons. It does not say what delete removes or whether an existing attribute is overwritten on name match.

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

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

Two sentences, zero filler, with the operation set stated first and the validation consequence second. Nothing repeats the schema or the title.

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

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

With an output schema, full annotation coverage and 100% parameter documentation, the description only needs to add operating context, which it largely does. The one real gap is the create-vs-update trigger: it says 'create, update' but never explains that an existing attribute under the same Term/name is replaced, which matters for a destructive, idempotent write.

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

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

Schema description coverage is 100% and the schema already documents the dialect/expression shape per kind, the status approval rule, and the datasource fallback. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

Names a specific resource ('named SQL expression under a Term') and the full set of operations it performs (create, update, certify, delete), which cleanly separates it from siblings like suggest_sql_attributes and validate_sql. An agent can tell it is the write path for persisting an expression, not the drafting or validation path.

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 four supported operations imply when the tool applies, but there is no explicit routing guidance — nothing tells the agent to draft with suggest_sql_attributes first, or to pre-check with validate_sql, or when to prefer this over update_term. The 'certified only when a person approved it' rule in the schema is the closest thing to a usage constraint, and it is not echoed in the 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?

Adds substantial behavior beyond the annotations: it discloses that previous Terms for the table are replaced with Terms carrying SQL attributes preserved, that new Terms are created as draft, that editing a certified Term's meaning reverts it to draft, and that unassigned candidate columns auto-attach to the first Term. One mild tension exists: annotations declare destructiveHint=false while the description says prior Terms are replaced — worth noting, though the replacement is scoped and partially exempted, so it is disclosed rather than contradicted.

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?

Four dense sentences, front-loaded with the core action, then replacement semantics and state transitions. No filler; a reader gets purpose and side effects in one pass.

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 write tool with rich annotations, a fully documented nested schema and an output schema, the description covers the key side effects an agent must know before writing. The main gap is workflow placement — which sibling to run before this and what to use for corrections.

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

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

Schema coverage is 100%, so the schema already defines table, terms, datasource, is_junction and column_descriptions in detail. The description adds only one extra semantic — that leftover candidate columns land on the first Term — which is useful but marginal against a fully documented schema; baseline 3 applies.

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

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

States a specific verb and resource: save Terms for one table and map its columns to them. This distinguishes it reasonably from update_term (single existing Term) and save_glossary (whole glossary), though no sibling is named explicitly.

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 context (proposing Terms for a table) but never says when to call this instead of update_term or save_sql_attribute, nor what preconditions exist (e.g. after describe_table/scan_datasource). Usage is inferable, not spelled out.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, but the description adds substantive context beyond them: what profiling actually inspects (samples, uniqueness, date formats, small value sets), how keys are inferred (by name, then confirmed by value containment), and crucially what survives a re-run (existing Terms and reviewed relationships). The one remaining gap is cost/scale — no warning that profiling samples rows and may be slow on large schemas, which matters since readOnlyHint=false signals it does persist inferred keys.

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

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

Two sentences, front-loaded with the core action, with no filler. The semicolon-chained clauses pack a lot of information but remain parseable, so the density costs only a little readability.

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 scanning/mutation tool whose annotations cover safety and whose output schema covers return values, the description supplies what matters: scope of the scan, inference methodology, and preservation guarantees. It stops short of stating runtime cost or required datasource permissions, which is the only notable omission.

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

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

Schema coverage is 100%, so the schema already documents all three parameters and the baseline of 3 applies. The description does add modest meaning by spelling out what the `profile` flag causes (sampling and value-level tests) and by implying `schemas` scopes the read, but it offers no guidance on the cost trade-off of disabling profiling or on when `datasource` can be omitted.

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

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

The description names a specific verb set (read/re-read, profile, infer, confirm) and a concrete resource (tables, columns, declared keys, column values). It is unmistakably about schema scanning and key inference, but it never contrasts itself with siblings such as check_readiness, add_datasource, or get_modeling_worklist, so an agent must still infer which of the 30+ tools is the right entry point.

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?

"Read (or re-read)" implies the two triggering situations — first onboarding of a datasource and a later refresh — and the closing sentence signals re-running is safe for curated content. However, no alternative tool is named and no exclusion is stated (e.g., when to prefer check_readiness or add_datasource first), leaving routing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful behavioral fact that results are IDs intended for follow-up via fetch, and that the search spans all datasources, but nothing about ranking, result limits, or failure 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?

Two tight sentences with no filler; the search scope comes first and the return-type hint follows. Slightly terse for the sibling ambiguity it leaves unresolved, but structurally sound.

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

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

For a single-parameter read-only search with an output schema present, the description is mostly sufficient — return shape need not be explained. The unresolved overlap with search_ontology is the main completeness gap for an agent choosing among 32 sibling tools.

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

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

Schema coverage is 100% but the schema's own parameter description is merely 'Search query.' The tool description adds no syntax, matching behavior, or format detail beyond that, so the baseline of 3 applies when the schema carries the burden and the description contributes nothing extra.

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

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

The description names a verb and resource ('Search the ontology documents (Terms and tables) across all datasources'), which is clearer than the bare tool name 'search'. However, it does not distinguish this tool from the sibling 'search_ontology', which by name appears to do the same thing, leaving the agent to guess which to call.

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?

'Returns ids for fetch' implies a follow-up workflow, which is useful implied guidance. But there is no explicit statement of when to use this versus search_ontology, list_terms, or lookup_values, and no exclusions or prerequisites are given.

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

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

Annotations already establish readOnly, non-destructive and closed-world, so the safety profile is covered. The description adds genuine context beyond them: it enumerates which object classes are searchable, discloses that stored record text surfaces as 'value' hits, and notes that another datasource's data can be reached via kind 'value'. It omits anything about ranking, result ordering, or how limit truncation behaves.

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

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

Three sentences, front-loaded with the scope enumeration and closing with the actionable 'Not semantic' directive. The middle sentence is heavy with a parenthetical that packs two ideas together, costing some readability, but nothing is padding.

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

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

An output schema exists, so return values need no explanation, and all four parameters are documented in the schema. The description supplies the remaining conceptual layer — what corpora are searched and what the 'value' kind does — which is what an agent needs 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 coverage is 100%, so the baseline is 3; the description pushes above it by explaining that kind 'value' is the mechanism for searching a different datasource's data and by characterizing the query string as business nouns, metrics, columns or values with synonyms/translation encouraged. The datasource/kind interaction is clarified in prose rather than left purely to the schema.

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

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

The opening sentence names a specific verb (lexical search) and enumerates the resource scope precisely: terms/concepts with bodies and relations, synonyms, mapped columns, SQL attributes, glossary, verified example questions, sources and unmodeled tables. It also declares what it is not ('Not semantic'), which separates it from any semantic-retrieval path, though it never names the concrete siblings (list_terms, get_term, lookup_values) that overlap its scope.

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 guidance is strategy-oriented rather than routing-oriented: 'use the schema's vocabulary, try synonyms, translate' tells the agent how to phrase a query, and the 'value' hint tells it how to reach another datasource's records. There is no explicit statement of when to reach for this tool versus list_terms/get_term/lookup_values, so the agent must infer the boundary from the enumerated scope.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavior: that reviewed decisions persist across re-scans and that only accepted joins feed join-path resolution, which is exactly the kind of downstream consequence an agent needs.

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

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

Three short sentences, verbs and resource front-loaded, with the persistence and join-path facts given as compact follow-ups. No filler or repetition of the title.

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

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

With an output schema present and full parameter documentation in the schema, the description is nearly complete for an 8-parameter mutation tool. The remaining gap is that it does not signal which actions require relationship_id versus source/target, and the 'annotate' wording conflicts with the 'update' enum value.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds little beyond the schema and actually introduces slight ambiguity: it says 'annotate' while the action enum offers 'update', so an agent cannot map that word to a concrete enum value.

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

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

The description names a specific resource (a join between two columns) and enumerates the operations (accept, reject, add, annotate, delete), so an agent immediately knows what the tool does. It does not explicitly contrast itself with siblings like list_relationships or find_join_path, which keeps it from a 5.

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

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

The sentences 'Reviewed relationships survive re-scans' and 'Only accepted relationships are used for join paths' implicitly explain why one would accept or reject, but the description never states when to use this tool versus list_relationships or find_join_path. Routing guidance is left to the schema's relationship_id note rather than the 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful context beyond that: candidates are mined from executed and verified queries, bridge tables, and column profiles, and include rules for judging them.

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

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

The description is two tight sentences with no wasted wording. It front-loads what the tool returns and then names the follow-up save action directly.

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

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

The tool is a read-only candidate generator with an output schema and fully described parameters. The description covers what it produces, where candidates come from, and the next step, though it could more explicitly clarify when to choose it over sibling discovery tools.

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

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

Schema description coverage is 100%, and all three parameters have clear descriptions in the input schema. The description does not add any meaning about the term, limit, or datasource parameters beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the resource as candidate SQL attributes and specifies what they include: reusable measures, filters, join patterns. It distinguishes the tool from save_sql_attribute by directing the agent to save good candidates there, though it opens with a noun phrase rather than an explicit verb.

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

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

The description implies usage by saying to save the good candidates with save_sql_attribute, which gives a clear follow-up action. However, it does not explicitly state when to call this tool, when not to call it, or how it compares to alternatives like get_modeling_worklist.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The description adds genuinely new context the annotations cannot express: that editing a certified Term's name or description silently demotes it to draft unless status is supplied. That is a real state-transition trap an agent would otherwise miss; it stops short of 5 only because the destructive-delete consequences (column mappings, SQL attributes) live in the schema rather than the description.

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

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

Two sentences, zero padding. The operation list is front-loaded and the certification side-effect follows as supporting detail, which is the right ordering for an agent scanning for fit.

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

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

With 10 parameters, an output schema, and rich annotations, most structured burden is already carried elsewhere, and the description covers the highest-risk gotcha. It does not mention the datasource parameter's single-datasource fallback or reinforce that delete is irreversible, but those gaps are modest given full schema coverage and an 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 description coverage is 100%, so baseline is 3. The description earns above baseline by explaining the interaction between the name/description parameters and the status parameter — a cross-parameter dependency the per-field schema text cannot convey on its own.

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 set tied to a concrete resource: 'Edit, certify, deprecate or delete a Term.' The enumerated operation modes let an agent distinguish this from read-path siblings like get_term, list_terms, and search_ontology without inspecting any schema.

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

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

Usage is implied rather than stated: an agent can infer this is the mutation counterpart to get_term/list_terms, but no sibling is named and no when-not-to-use condition is given. The one conditional sentence present ('unless you also pass status') is a behavioral caveat rather than a routing rule, so the guidance remains minimal-viable.

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

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

The annotations already declare a safe, non-destructive read with open-world access, so the safety profile is covered. The description adds meaningful behavior beyond that: it performs a dry run and reports Term certification status, which tells the agent the tool may execute against the datasource and returns governance metadata. It does not disclose cost, latency, or whether failures block execution.

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?

Purpose is front-loaded in the first clause, followed by a compact enumeration of checks. It is a single dense sentence but every clause names a distinct capability, so there is little waste, though it would scan better as a list.

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?

An output schema exists, so return values need not be explained, and the description covers the full set of validations an agent would want to know about. The only gap is operational context: whether validation is cheap, whether a dry run touches the datasource, and whether a failing check prevents execution.

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

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

Schema description coverage is 100% for both parameters, including the read-only SELECT constraint and the optional datasource default, so the schema carries the parameter burden. The description adds no parameter-level detail and does not mention the datasource parameter at all; baseline 3 applies.

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

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

States a specific verb and resource ('Check a query') and then enumerates the exact checks performed: read-only guard, unknown tables/columns, non-ontology joins, near-miss literals, fan-out under aggregates, dry run, and Term certification. That level of specificity clearly distinguishes it from run_sql and check_answerable.

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?

'Check a query before running it' establishes the workflow position relative to run_sql without naming the sibling. There is no explicit exclusion (e.g., when validation is unnecessary or when it should be skipped for trivial queries), so it falls short of a full when/when-not statement.

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