query_research_timeline

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

With no annotations provided, the description carries the full burden of disclosing behavior. It fully explains the tool's behavior: it returns all claims ordered by date, hides superseded claims by default, allows showing them via the show_superseded parameter, and supports filtering by entity (partial match) and date. No contradictions and complete 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 concise and well-structured: a one-sentence purpose, followed by a summary sentence, then a clear bullet-style list of parameters. Every sentence adds value with no redundancy. It is front-loaded with the primary purpose and efficiently covers all necessary details.

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 has an output schema (so return values need not be explained), the description is complete. It covers the three parameters thoroughly, explains the ordering and default behavior for superseded claims, and clarifies filtering logic. No gaps remain for an agent to understand how to invoke 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 0%, so the description must compensate fully. It does: each parameter is explained with clear semantics—entity (partial match, empty shows all), since_date (ISO date, optional), show_superseded (boolean, default False). This adds significant meaning beyond the schema's basic type and default info.

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 the temporal evolution of research beliefs.' It specifies that it returns claims for an entity ordered by date, showing how thinking evolved. This is a specific verb (query) and resource (temporal evolution of beliefs), and it distinguishes itself from siblings like search_memory or get_thinking_profile by focusing on temporal evolution with superseded claims handling.

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 clear context for when to use the tool (to see how beliefs evolved over time, to trace full reasoning chains by showing superseded claims). It does not explicitly name alternatives or state when not to use, but the specificity of 'temporal evolution' and 'research beliefs' makes the use case clear. A score of 4 is appropriate because it lacks exclusions but provides good contextual guidance.

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