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

There are no annotations, so the description carries the behavioral disclosure burden. It discloses a key non-obvious behavior: results are ACL-filtered so content the user lacks a role for is never returned. It also implies a read-only search operation and explains scope behavior. It does not describe result shape or pagination behavior, but the most important hidden behavior is covered.

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 at three sentences and front-loaded with purpose, followed by a key behavioral note and a scope usage tip. It has almost no waste, but the misleading backticked 'folder' reference costs a point against an otherwise clean structure.

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 description covers the most important non-obvious aspects: what content is searched, the ACL filtering behavior, and how to expand scope. However, with no output schema and six parameters, it gives no indication of the return shape, result ordering, or how matches are presented, and the folder/location ambiguity is a real gap. It is adequate but not fully complete.

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%, so the baseline is 3. The description adds high-level context about content types and the scope-widening behavior, but it does not add per-parameter detail beyond the schema. Its use of 'folder' where the schema has 'location' muddles rather than enhances the schema's already clear parameter documentation.

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 the verb 'Search' and clearly identifies the resource: organizational written knowledge, enumerating representative content types like policies, runbooks, decisions, and postmortems. This distinguishes it from siblings such as read_org_doc or list_org_docs, even though it does not name them explicitly. The minor 'folder' vs 'location' wording does not obscure the tool's overall purpose.

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?

It provides clear context for when to use the tool: when looking for information the organization has written down, with a notable ACL-filtering constraint. It also gives an explicit usage tip, 'omit folder to search everything you can reach.' However, it does not state exclusions or point to alternatives like list_org_docs for directory-style browsing, so it stops short of full routing guidance.

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