oncofiles

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 reveals important behavioral traits: returns entries with truncated content (500 chars), mentions filtering capabilities, and implies a search operation rather than data modification. However, it doesn't mention pagination behavior, rate limits, or authentication requirements that might be relevant.

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 perfectly structured and concise. It starts with the core purpose, then behavioral detail (truncated content), then usage guidance, then parameter documentation. Every sentence earns its place with zero wasted words. The parameter documentation is clearly formatted but not overly verbose.

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 complexity (7 parameters, search functionality) and the presence of an output schema (which means return values don't need explanation), the description is complete. It covers purpose, behavioral constraints (truncation), usage guidance, and comprehensive parameter semantics. With no annotations, it provides all necessary context for effective tool use.

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 provides excellent parameter semantics beyond the schema. With 0% schema description coverage and 7 parameters, the description fully compensates by explaining each parameter's purpose, format, and constraints (e.g., 'YYYY-MM-DD' for dates, 'comma-separated tags', specific enum values for entry_type and participant). This adds significant value beyond the bare schema.

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: 'Search the conversation archive by text, type, date, or tags.' It specifies the verb ('Search'), resource ('conversation archive'), and scope ('by text, type, date, or tags'). It also distinguishes from sibling 'get_conversation' by noting that tool provides full text while this returns truncated content.

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 alternatives: 'Use get_conversation for full text of a specific entry.' This clearly differentiates between search (multiple results, truncated) and retrieval (single entry, full text). The context of searching vs. retrieving specific entries is well-established.

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