Fs Search

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

Since no annotations are provided, the description carries the full burden. It discloses that the search is for a literal substring, that matches are confined to OPS_MCP_FS_ROOTS, and that paths escaping via '..' or symlinks are rejected. This is meaningful behavioral context about sandbox enforcement. It does not mention case sensitivity, recursion depth, or hidden-file behavior, so it is strong but not exhaustive.

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 two short sentences, front-loaded with the core action and qualifier. The second sentence adds essential security scoping without fluff. Every phrase earns its place, and the formatting with backticks aids readability. It is an exemplar of concise, high-signal description.

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 3 parameters, 1 required, and no annotation support. The description leaves 'max_results' completely unexplained and only vaguely gestures at 'root' through the sandbox mention. Although an output schema exists, the agent still needs parameter semantics to call the tool correctly. The lack of usage guidance compounds the incompleteness, making this insufficient for a frictionless call.

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 for the schema's lack of parameter documentation. It clarifies that 'query' is a literal substring and that results are restricted to the allowlisted roots, which indirectly relates to the 'root' parameter. However, it never explains the 'max_results' parameter, its default, or how 'root' narrows the search. Two of three parameters are not explicitly mapped to their purpose.

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 searches allowlisted filesystem roots for a literal substring. The verb 'search' and resource 'filesystem roots' are specific, and the 'literal substring' qualifier distinguishes it from regex or fuzzy searches. Among siblings like fs_read_file, the purpose is distinct and immediately understandable.

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 usage context is implied: this is the tool to use when you need to find a substring within allowed file system paths. However, there is no explicit guidance on when to prefer this over alternatives like fs_read_file, nor are there exclusion criteria or examples. The scope restriction to OPS_MCP_FS_ROOTS is stated, but not framed as a when-to-use condition.

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