sqlite

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

No annotations are provided, so the description carries full burden. It does disclose that docs_* results are pre-chunked and advises against file reads. However, it fails to mention that the 'exec' command can perform arbitrary SQL writes, and does not warn about destructive actions or the need for the 'write' flag. This is a significant transparency gap for a tool that can mutate the database.

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

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

The description is long but well-structured: a brief overview, a list of commands, then detailed explanations for each key command. Every sentence serves a purpose, and the use of bold command names and concise phrases makes it scannable. The density is justified given the tool's complexity, though it could be slightly trimmed for the most basic database commands.

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 docs_* commands are thoroughly explained, including behavior, params, and when to use them. However, the basic database commands (catalog, exec, list_databases, open_database, health_check) are only listed without any explanation of their purpose, return values, or side effects. Given that there is no output schema, the description fails to fully compensate for the complexity of the database operations.

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 description adds substantial meaning beyond the schema. It clarifies that the 'sql' param doubles as a search query for docs_search, and it details command-specific params like {chunk_id, before, after} for docs_context and {query, limit, threshold} for docs_search_in_doc. While the schema already covers 60% of parameters, the description fills gaps and provides practical semantics for the other 40%.

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's dual purpose: 'SQLite database operations + document-corpus search.' It then enumerates specific commands, and explicitly distinguishes between keyword search, semantic search, hybrid search, full-document retrieval, context expansion, and in-document search. This level of specificity and differentiation from siblings (retrieve, memory, kg) is excellent.

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

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

The description provides explicit when-to-use guidance for each docs_* command: 'Use for exact terms, API names, phrases' for docs_search, 'Use for general queries' for docs_semantic_search, and '*PREFER THIS*' for docs_hybrid. It also advises against file reads and recommends alternatives, making the usage intent crystal clear.

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