box_search_content

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

With no annotations provided, the description carries the full behavioral burden, but it discloses nothing beyond a bare 'search' verb. It does not reveal whether queries match file names, metadata, or content (relevant given the includeContent option), whether trashed items are excluded (includeTrashed defaults to false), or how results are ordered and paginated. The description adds no behavioral value beyond what the schema already exposes.

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 a single ten-word sentence with the verb and resource front-loaded ('Search Box') and zero filler. It is efficiently structured, though the brevity borders on under-specification rather than representing a model of economical completeness.

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 three parameters containing nested objects with eight subfields, no output schema, and no annotations, yet the description is only ten words. An agent cannot determine what the folders filter expects (IDs, paths, or names), what extension format to use, what includeContent does, or what the result shape looks like. This is insufficient for the tool's complexity.

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, yet it only hints that filters operate on files and folders — a loose mapping to the filters.type enum. The semantics of query, folders, extensions, limit, sortBy, direction, includeContent, and includeTrashed are left entirely unexplained. This adds only marginal value over the raw 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 uses a specific verb ('Search') with a clear resource ('Box' for files and folders), immediately identifying the tool as a content discovery utility. It distinguishes itself from read/save/share/analyze siblings implicitly, though it does not explicitly differentiate from the closely related box_explore_storage.

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?

'With optional filters' describes capability, not invocation context — it says nothing about when to use this tool versus box_explore_storage for browsing or box_read_document for retrieving a found item. No prerequisites, exclusions, or alternative routing guidance is provided. An agent must infer the tool's role purely from its name.

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