query_knowledge_base_document

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the tool is query-only (implied by 'Query'), it has a strict input requirement (CSV documents only), it processes natural language queries, and it returns results as markdown tables. It doesn't mention error handling, rate limits, or authentication needs, but covers the core operational behavior well.

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 efficiently structured with three sentences that each serve a distinct purpose: stating the core function, specifying the CSV-only constraint with prerequisite guidance, and describing the output format. There's no wasted text, and important information is front-loaded with 'IMPORTANT' emphasis.

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 (2 required parameters, no output schema, no annotations), the description provides good coverage. It explains what the tool does, when to use it, how to prepare inputs, and what format results will take. The main gap is lack of output schema documentation, but the description compensates by specifying 'Results are returned as a markdown table.'

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 fully documents both parameters. The description adds some context about document_id sourcing (list_knowledge_base_documents with CSV filter) and query examples, but doesn't provide significant additional semantic meaning beyond what's in the schema descriptions. This meets the baseline expectation when schema coverage is complete.

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 purpose: 'Query a CSV document from the knowledge base using natural language.' It specifies the exact resource (CSV document), the action (query with natural language), and distinguishes it from siblings by emphasizing it ONLY works with CSV documents, not other document types.

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 guidance on when to use this tool: 'This tool ONLY works with CSV documents.' It also specifies prerequisites: 'Use list_knowledge_base_documents with filters='file_type:csv' to find CSV document IDs (search_knowledge_base results also contain document IDs).' This clearly tells the agent how to obtain the required document_id parameter.

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