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

With no annotations, the description carries the full burden and does well: it discloses return semantics beyond structure, explaining that a statistic with no drift event did not change and that unevaluated_tables means the table was not compared. Pagination behavior ('changes is paged in recorded order with total and next_cursor; every other key rides the first page whole') is also disclosed, though permissions/auth and error behavior are not.

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 the core purpose, then structured as return-shape, edge-case semantics, pagination, and sibling boundary. Sentences are dense and clause-heavy but each carries distinct information, and there is 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?

No output schema exists, so the description must explain the return document, and it does: summary, changes, total, next_cursor, and the unevaluated_tables caveat. For a read-only paged diff tool this is close to complete, missing only failure/auth context.

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

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

Schema description coverage is 100%, so the schema already documents kind, table, cursor and connection. The description's cursor/connection remarks largely restate the schema descriptions, adding little beyond them, 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 a specific verb+resource ('what changed between the database's last two prints') and unambiguously scopes it as a diff over recorded changes rather than current state. It explicitly draws the boundary with the sibling get_table_context, so an agent can distinguish the two without opening either 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?

It states when this tool is the right answer (you want what changed, not current state) and names the alternative (get_table_context) with the condition that selects it. It stops short of covering the remaining siblings or stating explicit when-not conditions, but the routing guidance is clear.

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

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

No annotations, so the description carries the full burden. It discloses non-obvious behavior: the `tables` map is paged in FQN order with `total`/`next_cursor`, every other document key arrives only on the first page, and `failed_tables` is filtered by `pattern` like `tables`. It omits the safety profile (read-only implied but unstated) and error/auth behavior, but the pagination semantics are the load-bearing disclosure here.

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-loads the core purpose, then usage routing, then pagination mechanics. Dense and mostly waste-free, though the opening clause is syntactically tangled ('its tables and the files each has, not a semantic catalogue of what they mean').

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

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

With no output schema and no annotations, the description must convey return shape, and it does: `tables` map, `total`, `next_cursor`, and the first-page-only rule for other keys. Only the safety profile and any error/refresh behavior go unstated for a 3-param read tool.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, making 3 the correct baseline. The description corroborates rather than extends: it clarifies that `pattern` filters both `tables` and `failed_tables` and that `cursor` is the previous page's `next_cursor`, but adds little syntax or format detail 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 concrete verb+resource: returns a connection's index of tables and the files each has, and explicitly contrasts itself with a 'semantic catalogue of what they mean' (the get_table_context role). It distinguishes from list_tables too, though the phrase 'the print's index' is unexplained jargon that adds fog rather than precision.

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 ('an index field no other tool projects') and a when-not with a named alternative plus its condition: 'for table names, row counts and staleness, list_tables with detail: true is shorter and already judges each table's freshness.' An agent can route correctly without opening another schema.

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

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

No annotations are provided, so the description carries the full burden, and it does reasonably well: a section returns its own text and lists its direct subsections, results are paged like get_table_context's markdown, and the guide is version-bound rather than print-bound. It omits auth requirements, error behavior, and page-size limits, which keeps 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?

Purpose is front-loaded in the first sentence and every subsequent sentence adds a distinct constraint (subsections, pagination, version scope, dependency scope). It is dense and slightly compressed in places ('Paged like get_table_context's md'), but there is little fat.

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

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

With no output schema, the description steps in to describe the return shape (section text plus its direct subsections) and pagination, which is exactly what an agent needs. It leaves out cursor expiry or error semantics, but for a read-only documentation lookup it is nearly complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains the spec_ref-citation workflow ('§2.2.4', 'ASSERTIONS.md §1.4'), clarifies that any heading depth works, and ties omission of `section` to the table of contents. That workflow context is not in the schema itself.

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: look up the dbprint format spec, the assertion DSL spec, or the reading guide, resolving field meanings and spec_ref citations. It explicitly distinguishes itself from siblings by noting it depends on no connection or print, whereas what a print's tables hold is get_table_context's and list_tables' answer.

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 clear conditions: omit `section` for the heading tree, use a section number or a spec_ref copied verbatim from a finding, and use a heading's text for the guide. It also scopes the answer ('the guide this dbprint version ships, not the copy stored with a print'), though it never states a negative case for when NOT to reach for this tool beyond the implicit sibling contrast.

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

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

With no annotations, the description carries the full burden and delivers: it discloses pagination semantics (next_cursor line in md/yaml vs a json key, sections continue rather than being dropped), the _corrupted field for unparseable files, the md-vs-json/yaml rendering difference for Notes/statistics, and the omission of column sketches (pointing to the dbprint:// statistics resource). This is rich behavioral context an agent cannot get from structured fields.

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 the core action, then organized by concern (purpose modes, routing, paging, format differences). It is dense and long for a single paragraph, and the query-mode content list is partially restated in the schema, but nearly every sentence carries distinct operational 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?

With no output schema and no annotations across 9 parameters, the description compensates fully: it enumerates what each mode returns, how each format renders it, how paging terminates, and where to find raw statistics. Nothing an agent needs to call this 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%, so the baseline is 3, but the description adds real meaning: it explains that query omits statistics while profile carries them, that include_stats has no effect under query, that connection is only needed on multi-database servers, and that include_relationships switches to the Joins list under query. It adds value beyond the per-parameter prose without fully re-specifying every default.

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

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

Opens with a specific verb+resource ('Read one table') and immediately distinguishes the two modes (purpose: query vs the default profile) with concrete content lists for each. It names the siblings it is not (search_columns, list_tables, resolve_value) so the agent can route without opening other 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?

Gives explicit when-to-use instructions: call with purpose: query before writing SQL against a table, and use search_columns or list_tables first when the table is not yet known, with resolve_value for spelling checks. Alternatives and their triggering conditions are all stated, not 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?

No annotations are provided, so the description carries the full burden, and it discharges most of it: it discloses what detail:true projects (type, row_count, columns, profiled_at), the freshness verdict vocabulary (live/stale/dormant), the threshold_error fallback, and pagination semantics (total always present, next_cursor while more remain). It omits permission/auth requirements and any rate-limit or cost behavior, which keeps 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?

Front-loaded with purpose and alternative routing before descending into the detail-flag payload, so an agent can stop reading early. The middle clause about freshness verdicts is dense and slightly over-packed for the 10% weight it carries, but no sentence is wasted.

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

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

There is no output schema, so the description must explain return values, and it does: bare FQN strings by default, the enriched fields under detail:true, the verdict logic, and the paging envelope with total and next_cursor. Combined with the connection-omission error note, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is already 100%, so parameter documentation is largely handled there and the baseline is 3. The description adds genuine meaning beyond the schema by explaining what the projected fields mean and what verdicts imply, and by noting the connection-missing error lists available connections. Pattern/cursor semantics are essentially restated from the schema rather than extended.

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 ('List a connection's tables') plus a scoping modifier (fnmatch pattern over dotted names). It explicitly distinguishes itself from siblings ('To find columns rather than tables, use search_columns; for the print's raw table index, get_manifest'), so an agent can route without opening 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?

Gives a positive use case ('see which tables exist, their row counts, and whether statistics are stale') and names two explicit alternatives with the condition that selects each ('To find columns rather than tables, use search_columns; for the print's raw table index, get_manifest'). Nothing 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?

With no annotations the description carries the full burden and mostly does: it enumerates the reply variants (stored/definition/nearest/none/unavailable), the `coverage`/`listed` fields, the sample caveat, `exhaustive`/`scope`/`row_count`, and paging semantics. It never explicitly states the operation is read-only or side-effect-free, leaving safety to inference.

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 and the key filter caveat are front-loaded, and most sentences carry real information (reply precedence order, sampling caveat, paging). It is dense and idiom-heavy ('the print', 'rides along whole', 'lost it on the latest print'), which slightly hurts scannability but isn't wasted words.

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

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

There is no output schema, so the description must explain return values, and it does thoroughly — reply variants, coverage/listed counters, sample caveat, `domain` for small vocabularies, partial-read `scope`/`row_count`, and paging order. Nothing an agent needs to call and interpret this tool correctly is missing.

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

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

Schema description coverage is 100%, so the six parameters are already documented (including `part` path syntax and `cursor`). The description adds only marginal parameter-level meaning, mainly paging notes that are really about the reply shape; 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?

States a specific verb+resource+scope: resolving a phrase/code/spelling against one column's published values. It explicitly distinguishes itself from sibling `get_table_context` by describing the exact gap it fills ('whose stored spelling get_table_context does not already list in full').

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?

Names the trigger condition clearly — use before writing a literal into a filter when the stored spelling isn't fully listed by `get_table_context` — and the `unavailable`/`none` branches hint at when it won't help. It stops short of explicit when-not guidance or naming other siblings, but the context is concrete.

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

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

No annotations are provided, so the description carries the full burden — and it delivers: ANDed filter semantics, pagination (total, next_cursor), partial-scan scope blocks, sampling behind looks_like verdicts, and two distinct failure surfaces (unreadable_tables, switched_off_tables) with the differing consequences of statistics vs annotation failures. This is unusually rich behavioral context for a read 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?

Well front-loaded — purpose, then routing, then filter semantics, then return/paging behavior. It is dense and long, and the closing sentences on unreadable_tables/switched_off_tables are heavy, but with no output schema the detail is load-bearing rather than 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?

With no output schema and 10 optional parameters, the description compensates fully: it describes the shape of a match, echoed classification fields, candidate_key_exception, page metadata, and conditional error fields. An agent has everything needed to call it and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond it: it explains that filters are optional and ANDed, gives concrete combined examples (looks_like: email, sensitivity: contact), and clarifies that filtered fields are echoed back on matches.

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 precise verb+resource ('Find columns across every table') and immediately frames the discovery scenario ('the first call when the table holding a fact is not yet known'). It explicitly distinguishes itself from siblings that could be confused with it.

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 explicit when-to-use ('first call when the table holding a fact is not yet known') and names both alternatives with their selecting conditions: get_table_context to read a found table, list_tables when you want tables rather than columns. No inference required.

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