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

Annotations only provide destructiveHint=false, so the description carries the transparency burden. It adds key behavioral context: no migration or schema upload, credentials stored sealed server-side and never echoed back, and the return of a new dbId plus schema preview. This is substantive and does not contradict 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?

The description is two crisp sentences that front-load the core purpose, then provide usage, security, and return information. Every phrase earns its place; no fluff or repetition of schema field names beyond necessary context.

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 moderate complexity and lack of output schema, the description covers the goal, required inputs, security behavior, and return value. It lacks explicit error-handling or network/prerequisite details, but the essential flow (connect, get dbId, query later) is clear, making it fairly 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%, so the schema already documents all three parameters. The description mostly reinforces existing schema details (engine and connection URL) without adding new semantic meaning. It does not explain the 'name' parameter beyond what schema provides, yielding a baseline score of 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?

The description states a specific action (Connect an existing ClickHouse or Postgres database) with a clear purpose (so the agent can query it in natural language with nlqdb_query). It clearly distinguishes this tool from siblings like nlqdb_query by positioning it as the setup step that returns a dbId for later queries.

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

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

The description gives clear context: use this to connect an existing database, pass engine and connection URL, and it enables subsequent nlqdb_query calls. It implies the tool should be called before querying, but it doesn't explicitly state when not to use it or name alternatives such as nlqdb_remember or nlqdb_list_databases.

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 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?

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 state destructiveHint=false, so the description carries the burden. It reveals deterministic behavior (no LLM), direct schema materialization, rejection of non-memory DBs, and upsert behavior for entity kind. This fully covers behavioral traits.

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, front-loaded with the core purpose. It is concise and structured, with no redundant 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?

Given the absence of an output schema and the complexity of parameters (nested objects, enums), the description covers the main points well: purpose, constraints, and relationship to query tool. It could mention return value, but that is a minor gap.

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 parameters are already explained. The description adds context by explaining the overall purpose and the role of each kind, but does not provide new details beyond what the schema offers. The deterministic note adds 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 clearly states the tool writes a typed row into the agent's memory database, listing three specific kinds (fact, episode, entity). It distinguishes from sibling tools (nlqdb_query for reading, others for listing/describing/connecting) by focusing on the write operation.

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

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

The description explains when to use the tool (to remember facts/episodes/entities) and references nlqdb_query for querying. It also specifies the DB must be an agent_memory_v1 preset. However, it does not explicitly state when not to use it or mention alternatives beyond querying.

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