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

Adds substantial behavior beyond annotations: DDL runs, an index is built CONCURRENTLY, the ledger records the deciding key, verification measures the targeted query after the window, and a regression triggers automatic revert via the stored inverse. The idempotent no-op with replayed: true is also disclosed.

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

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

Front-loaded with the core action and packed with relevant behavior in two tight sentences. The parenthetical and em-dash clauses each carry distinct operational meaning, so nothing 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?

Given the mutation complexity and no output schema, the description covers the important side effects and idempotency well. It only partially describes the return payload beyond replayed: true, leaving a minor gap for an agent that needs the full response shape.

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 single id parameter is already documented well. The description adds the retry/no-op behavior for the same id, but does not add syntax or constraints beyond what the schema and annotations provide.

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?

State a specific verb and resource: 'Apply a proposal on the attached database.' It goes beyond a restatement by explaining the DDL execution, ledger recording, verification, and automatic rollback, and its contrast with the sibling reject_proposal is clear from the 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 establishes when to use it: a proposal exists on the attached database and its id comes from nlqdb_list_proposals or nlqdb_connect_database. It also explains replay behavior, though it does not explicitly state when not to use it or name reject_proposal as the alternative.

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 declare destructiveHint=false, so the description carries the real burden and does so well: it discloses the side effect (the DBA starts watching the database on Postgres), the credential handling guarantee (stored sealed server-side, never echoed back), and the return shape (dbId, schema preview, first proposal set). It stops short of idempotency on re-connect (duplicate dbId?) or auth/permission prerequisites.

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 dense sentences, front-loaded with the verb and resource, then side effects, then return value. "No migration, no schema upload" is a worthwhile disambiguation rather than filler, though the credential-storage clause is stated twice within the same paragraph.

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 correctly compensates by enumerating what comes back (dbId, schema preview, Postgres proposals). Combined with the sealed-credential note and engine options, an agent has everything needed to call it correctly; only failure/duplicate-connection behavior is unspecified.

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 already documented with an enum on engine and format examples on connection_url. The description only restates "pass the engine and a connection URL" and repeats the sealed-credential note already present in the schema, so it adds little beyond the structured data.

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 ("connect (attach) an existing Postgres or ClickHouse database") and immediately ties it to its downstream consumer (nlqdb_query). The supported engine list is named inline, so an agent can rule the tool in or out without opening 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?

Clear context for when to use: onboarding an existing database so it can be queried in natural language, with the explicit reassurance "no migration, no schema upload" that rules out a migration-style interpretation. It does not name a when-not condition or point at siblings such as nlqdb_list_databases for checking whether a connection already 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?

The readOnlyHint annotation already indicates a safe read operation, and the description adds context by specifying the exact metadata returned and the required key type. This goes beyond the annotation without contradicting it, but does not disclose potential error or edge cases.

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

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

The description is three concise sentences, each with clear value: the operation, the return structure, and the auth prerequisite. No redundant or filler content is present.

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

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

Given the tool's simplicity (one parameter, no output schema, no nested objects), the description covers all necessary aspects: purpose, return value, and prerequisites. The description fully compensates for the lack of an output schema by explicitly listing the metadata fields returned.

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 single 'db' parameter is described in the schema as 'Database id or slug to describe,' and the tool description does not add any additional parameter-specific detail beyond that.

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

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

The description clearly states a specific action ('Inspect the shape of one of your agent's memory databases') and specifies the return value ('schema metadata (slug, engine, schema name)'). This distinguishes it from siblings like list_databases and query, which handle listing and querying respectively.

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

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

The description explicitly notes it operates on a single database, contrasting with list_databases. It also mentions the auth requirement ('Requires a user-scoped key'), though it does not explicitly name alternative tools or provide a 'when not to use' exclusion.

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 flag destructiveHint=true; the description supplies the substance behind it — schema widening happens in the same transaction, column types are inferred from values, naming is snake_cased, and the DDL that ran is returned. It doesn't say that the created table/columns persist and cannot be undone if the write was a mistake, which is the one behavioural consequence of the destructive hint left implicit.

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

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

Front-loaded with the core action and its no-modelling trait, then the upsert rule, then the return shape, then the sibling routing. It is dense but every clause carries information; slightly heavy punctuation and a couple of restated points (no model call appears twice) keep it from a 5.

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 and explains the return values (stored rows with generated ids, plus the DDL when the schema widened). Combined with the disclosed write limits and upsert behaviour, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% and the schema already spells out `key` upsert semantics, value→type mapping, and the 1000-row cap in detail. The description restates the same facts ('Pass `key` to upsert', 'typed from the values') without adding syntax, format, or edge-case meaning beyond the schema, 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?

States the specific verb and resource ('Insert structured rows into a table') and immediately names the distinctive trait — no data modelling, unseen tables/fields auto-created — that separates it from nlqdb_query. An agent can pick between this and its siblings 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?

Gives an explicit selection rule: 'Use it whenever you hold the exact values; use nlqdb_query to write something described in words.' It also states when to use the `key` parameter (upsert / safe re-import), so both tool choice and mode choice are covered.

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, so the read-only nature is known. The description adds the auth requirement (user-scoped key) and the return format ('engine per row'), which exceeds what annotations provide and helps set expectations.

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

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

Three short sentences each carry distinct value: purpose, auth requirement, and return format. The description is front-loaded with the primary action and contains no filler or redundancy.

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

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

For a zero-parameter listing tool, the description covers all essential aspects: what is listed, scope, authentication prerequisite, and return shape. No output schema exists, so the description appropriately compensates by mentioning 'engine per row'.

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

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

The tool has zero parameters, so schema coverage is trivially 100%. Baseline 4 applies, and the description appropriately mentions the scope and auth context without needing to explain parameter syntax.

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

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

The description uses a specific verb ('List') and resource ('memory databases') with clear scoping ('scoped to the authenticated user'), making the operation unambiguous. It also distinguishes itself from siblings like query or remember, which perform different actions.

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

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

Provides useful context: the tool lists databases the agent can query and requires a user-scoped key. It does not explicitly name alternatives or when-not-to-use, but the naming and description sufficiently imply the intended use case.

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

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

With readOnlyHint=true already covering safety, the description adds real substance: it enumerates what each proposal contains (undo statement, rationale) and notes that decided proposals carry verify's measured p95 before/after only once the observation window has passed. That timing caveat is the kind of context annotations cannot express.

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 dense sentence that front-loads the core purpose before the payload details and the dbId instruction. It is information-rich with little waste, though the nested clauses make it slightly harder to parse than it needs to be.

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

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

For a one-parameter read tool with no output schema, the description covers purpose, the parameter's provenance, and the shape of the returned items, including the conditional p95 data. Missing only explicit guidance on what to do with the results (apply/reject), which the sibling tools would cover.

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?

Single parameter with 100% schema coverage, so the schema already documents `db` fully. The description's 'Pass the dbId nlqdb_connect_database returned' merely restates the schema's own text, adding no new syntax or format detail — baseline 3.

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 what nlqdb's DBA proposes for an attached Postgres') and spells out the payload — index, undo statement, reason, plus already-decided items with measured p95. This is clearly distinguishable from the sibling nlqdb_apply_proposal / nlqdb_reject_proposal, which act on those proposals.

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?

Establishes the prerequisite explicitly ('Pass the dbId nlqdb_connect_database returned'), which sequences the agent after connecting. It stops short of naming alternatives or exclusions — e.g. that this is the review step before nlqdb_apply_proposal / nlqdb_reject_proposal — so routing to siblings is left implicit.

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?

Beyond the destructiveHint annotation, the description discloses the two-step confirmation for destructive plans (requires_confirm + diff, then confirm: true), the auto-creation of the database on first reference, and the return of rows along with compiled SQL in trace. These details give the agent a clear understanding of side effects and expected output.

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

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

The description is three sentences, each delivering unique value: purpose and capabilities, return values and auto-creation, and destructive confirmation. It is front-loaded and free of redundant or filler content.

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

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

With no output schema, the description adequately covers return behavior (rows + SQL trace) and critical side effects (auto-creation, destructive confirm flow). Parameter descriptions handle errors like ambiguous_db and model_unavailable. It could be slightly more explicit about result formatting, but given the tool's complexity, it is sufficiently complete.

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

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

The input schema already provides 100% parameter descriptions, including examples, edge cases, and enumeration. The tool description adds no further parameter semantics beyond what the schema states; even the confirm behavior is repeated verbatim from the schema. Baseline 3 is appropriate as the schema handles 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 states the tool queries the agent's structured memory in natural language, emphasizing its capability for GROUP BY/JOIN/aggregate operations. It distinguishes itself from simple recall and the sibling tools by positioning itself as a real database query interface.

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 this tool is for structured queries involving joins or aggregations, contrasting with 'not just recall' which hints at nlqdb_remember. It also explains the confirmation flow for destructive plans, guiding when confirm is needed. However, it does not explicitly name alternatives for listing or connecting databases, so it lacks a fully explicit when/when-not structure.

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 mark readOnlyHint: true, but the description goes much further: it guarantees no write/create/modify, states that plan-to-change requests are refused, discloses auto-target behavior and the ambiguous_db edge case, and tells the agent it returns rows plus compiled SQL. This is rich, non-contradictory behavioral disclosure well beyond structured hints.

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 sentences, all value-dense and front-loaded with the core purpose and safety guarantee. Each sentence delivers a distinct piece of actionable information — behavior, exception, db targeting, return format — without repetition. It is concise but not under-specified.

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

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

The description is fully self-contained for a read-only natural-language query tool. It covers the safety contract, failure cases (ambiguous_db, no db, now database), model selection, and the exact return output (rows + compiled SQL). Given the lack of an output schema, this description effectively compensates by disclosing the return shape.

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?

Although schema coverage is 100%, the description adds meaningful semantic context: `db` can be omitted to auto-target the only database, but with several it returns candidate IDs; `model`'s 'best' presets require specific account conditions; 'unique' is the default for nlqdb to choose. This goes beyond the schema's basic parameter docs, clarifying real usage nuances.

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

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

The description uses a specific verb+resource pattern: 'Read-only natural-language query over your agent's memory — SELECT / aggregate / JOIN over existing data.' It clearly distinguishes this from sibling nlqdb_query and from a generic list/connect tool by emphasizing it never writes. The tool's intent is immediately transparent.

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

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

Explicit guidance is given: 'a request whose plan would change data is refused (use nlqdb_query for that), so this tool is safe to mark always allow.' It also explains when to pass `db` vs. auto-targeting and touches on ambiguous-database behavior. This leaves little ambiguity about when to use this tool versus alternatives.

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

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

Goes beyond the annotations by stating the side-effect profile: nothing runs on the database and the proposal is 'never proposed again', which tells the agent the rejection is durable. Idempotence and non-destructiveness are already in annotations, so no credit is needed there. What is missing is what happens with an invalid or already-decided id.

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, front-loaded with the action and its consequence, then the parameter guidance. 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?

For a two-parameter mutation with no output schema, the description covers the essential behavioral fact (nothing executes) and the reason field. Only error/edge-case behavior on invalid ids is left unspecified.

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 both parameters are fully documented in the schema; the description only echoes the reason guidance with an example. Baseline 3 applies because 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?

States a specific verb ('Decline') and resource ('a proposal') and the goal is unmistakable, distinguishing it from nlqdb_apply_proposal by implication. It does not name the sibling explicitly, but the action 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?

Usage is implied — you reject a proposal you don't want executed — but there is no explicit statement of when to reject versus apply or edit, and no prerequisites or error conditions mentioned.

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 provide only destructiveHint=false, so the description must cover the write behavior. It explains that writing is deterministic, materializes directly into a schema, and describes auto-provisioning of the database on first use. It also hints that facts with a TTL expire and are filtered out, and entities are upserted in place. However, it does not explicitly state that writing is not read-only beyond the annotation's implication – a small gap but overall strong transparency.

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

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

The description is packed with valuable details but is somewhat lengthy. Each sentence adds meaning, though some repetition occurs (e.g., the TTL concept appears in both `payload` and `ttlSeconds` descriptions). It is front-loaded with the core purpose, making the rest readable. A bit more brevity could improve it.

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

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

Given 6 parameters (2 required) and no output schema, the description covers all key aspects: how to start, parameter semantics, expected results (dbId, db_created), and how to query later. It lacks an explicit note on error handling beyond the wrong_preset for `db`, but overall it is sufficient for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, yet the description adds significant value beyond the schema. For `kind`, it explains the semantics of each enum option (snapshot vs time-bound vs append-only). For `payload`, it provides detailed structure per kind and advice on query design. For `ttlSeconds`, it describes expiration behavior and usage patterns. The description transforms raw schema fields into actionable guidance.

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

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

The description clearly states the tool writes a typed row into the agent's memory database, listing three use cases (fact, episode, entity) and distinguishes it from siblings like nlqdb_query by specifying this is the write side. It also explains the deterministic behavior without an LLM in the loop.

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

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

Provides explicit guidance on when to omit `db` for first use, how to pin the returned `dbId`, references sibling tool nlqdb_query for reading back the data, and gives detailed instructions on choosing among kind values and whether to use entity vs fact. It also advises on superseding old facts rather than accumulating stale rows.

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