retrieve_chunks

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

With no annotations, the description carries the full burden. It thoroughly explains the behavior: it accepts one or more queries, returns structured chunks with listed fields, and instructs the LLM to synthesize evidence-based answers. It doesn't explicitly state read-only behavior or rate limits, but 'retrieve' implies it, and the return format and no-side-effect expectation are clear.

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 well-structured with a clear opening sentence, a bulleted list of best practices, and a final paragraph about return fields and follow-up synthesis. It is somewhat lengthy but every section earns its place by providing practical guidance. The bullet points improve scanability.

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 complexity of 5 parameters, nested objects, and no output schema, the description covers all key aspects: what the tool does, how to structure queries, when to use filters, and what fields are returned. It also provides downstream instructions for the calling LLM. It doesn't mention error handling or pagination, but these are not essential for the tool's core purpose, so the completeness is high.

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 schema already provides 100% coverage of parameter descriptions. The description adds meaningful guidance beyond the schema, such as recommending 3-5 keyword-dense query variations, using array syntax instead of full sentences, and explaining how filters and date parameters should be used. This elevates the semantic clarity beyond the baseline.

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 runs Chronicle retrieval for a string or list of sub-queries and returns standardized chunks with metadata. It mentions optional date window and metadata filters, and the first sentence is specific and action-oriented. The sibling 'health_check' is clearly unrelated, so this tool is well-differentiated.

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 includes a dedicated 'Best practices for the calling LLM' section with explicit guidance on decomposing complex questions, using array syntax, applying filters, and using date filters. It tells the agent exactly when and how to use the tool, effectively substituting for absence of sibling alternatives.

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