search

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

No annotations were provided, so the description carries the full burden of behavioral disclosure. It effectively reveals key behavioral traits: returns ranked results but not full content, uses pagination via cursor/next_cursor, and has type-specific result sources. It also notes rate limits (Trial max 10, Pro max 50). This is rich, honest contextual disclosure beyond what a schema would convey.

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 clear section breaks: main purpose, usage, strategy, and args. It is front-loaded with the core statement, then detail. It is longer than a minimal two-sentence description, but nearly every sentence adds value. Minor redundancy exists (query keyword advice appears twice, once in strategy and once in args), which prevents a perfect 5.

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 tool has no output schema and complex behavior with multiple content types, pagination, and strategic search guidance. The description thoroughly covers what the tool does, when to use it, how to use the parameters, what the results include, and how to follow up with other tools. It is complete enough for an agent to select, invoke, and process results 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?

The schema provides no description coverage (0%), so the description's parameter docs are essential. It adds substantial meaning beyond the raw schema types: query gets keyword-count guidance and language advice, type gets a complete enumerated list of content types and their sources, limit gets a range and tier-specific cap, cursor is explained as an opaque pagination token tied to next_cursor. This far exceeds basic schema information.

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 opens with 'Search documents' which is a specific verb+resource pair, and immediately clarifies what it returns: 'ranked results with title, author, year, description, url, id, score — not full content.' It distinguishes itself from the sibling tool 'detail' by explicitly directing users to 'Use detail() for full metadata on promising results.' This clearly separates the search function from a detail-retrieval function.

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 an explicit 'Use when:' section that lists a broad but specific set of user intents (research, find papers/books/articles, look up facts, find discussions, legal cases) and generalizes to 'any "search for..." request.' It also gives guidance on alternatives: using fetch/browsing for full content and using detail() for metadata. This goes beyond simple usage indication and provides actionable decision rules.

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