browse_documents

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

With no annotations present, the description carries the full burden of behavioral disclosure_RESPONSIBILITY. It discloses meaningful behaviors: the default bare-call result, folder-by-folder drilling, relevance ranking behavior inside read-only shared folders, and the root-level ranking limitation ('at the library root it ranks only your own documents'). It does not discuss permissions or errors, but for a retrieval tool the disclosed navigation and ranking semantics are substantial.

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 compact but information-dense: first sentence establishes primacy, second explains the core browsing workflow, third covers relevance sorting, and the last gives an explicit anti-guideline. Every sentence contributes a distinct piece of guidance and the most important routing rule is front-loaded.

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 six parameters, no annotations, and no output schema, the description plus parameter schemas fully cover what an agent needs to select and invoke the tool: how to start, how to drill down, when to use relevance, when to use recursive, and how to avoid prematurely escalating to search_documents. Nothing critical is missing for correct invocation.

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 100%, and the schema already documents each parameter's meaning, defaults, and allowed values, including the 'next_offset' pagination contract)Skip. The tool description adds strategic usage context around parameters, but does not materially add semantics beyond the schema's own parameter descriptions. Baseline 3 is appropriate.

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 names the tool as the 'Primary document retrieval tool' and explicitly distinguishes it from search_documents(), telling the agent to use browse_documents for 'all document-related questions' and treating search as an escalation path. It states a concrete behavior: 'bare call returns root-level sub-folders and documents; pass folder_id to drill into a sub-folder level by level.' This clearly separates it from siblings like get_folder_structure and search_documents.

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 gives explicit when-to-use guidance: 'After orienting with get_folder_structure()... use this for all document-related questions.' It also gives an explicit exclusion: 'Do NOT jump to search_documents() first — it is an escalation path, only after browse_documents(sort="relevance") has failed.' It further explains when to use recursive browsing and when the relevance sort is appropriate.

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