search_link

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

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'autocomplete' behavior which is helpful, but doesn't describe important aspects like whether this is a read-only operation, what the response format looks like, pagination behavior, rate limits, authentication requirements, or error conditions. The mention of 'page_length' hints at pagination but doesn't explain how it works.

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 reasonably concise with a clear purpose statement followed by parameter explanations. However, the parameter section uses inconsistent formatting (some parameters get brief explanations while others don't), and the overall structure could be improved by grouping related information. The description earns its place but could be more efficiently organized.

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 that there's an output schema (which handles return values) but no annotations and 0% schema description coverage, the description is incomplete. It covers the basic purpose and parameters at a surface level but lacks crucial behavioral context, usage guidance, and detailed parameter semantics. For a search tool with 4 parameters in a system with many document-related tools, more comprehensive documentation would be expected.

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. It provides basic parameter names and minimal descriptions ('DocType to search in', 'Search text', 'Optional JSON string of filters', 'Max results'), but doesn't explain what constitutes a valid doctype, how the search text is matched, the format of filters JSON, or what 'max results' means in practice. The parameter explanations are too brief given the complete lack of schema descriptions.

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 as 'Search for link field values (autocomplete)', which specifies the verb (search), resource (link field values), and behavior (autocomplete). It distinguishes from siblings like list_documents or get_document by focusing on link field autocomplete rather than general document operations. However, it doesn't explicitly contrast with other search-related tools that might exist.

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 no guidance on when to use this tool versus alternatives. It doesn't mention when this specific link field search is appropriate compared to general document searches (list_documents) or other lookup tools. There's no context about prerequisites, limitations, or typical use cases for link field autocomplete functionality.

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