agentic_file_workflow

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

Goes well beyond the annotations by disclosing the sampling dependency, the NO_CONTEXT requirement for an MCP client that injects Context, the SAMPLING_ERROR failure mode, and a full return/error envelope. The remaining gap is the unexplained interaction between the "no tools" claim and the required available_tools parameter, which leaves the execution model ambiguous.

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?

Front-loaded with the core mechanism in sentence one, then organized under clear headers (Return Format, Recovery, Examples). "Args: See Parameters block." is pure filler, and the duplicated Return Format block is partly redundant with the existing output schema, but overall it is well-structured rather than bloated.

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?

An output schema exists, so restating the return shape is optional, and the failure/recovery paths are well covered for a tool with a sampling dependency. What's missing is any description of max_iterations semantics or the delegation behavior behind available_tools, which an agent needs to invoke this correctly.

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 coverage is 0% and the description explicitly defers with "Args: See Parameters block," adding nothing for workflow_prompt or max_iterations (max_iterations is never mentioned at all). Only the examples give indirect shape to workflow_prompt and available_tools, which is insufficient for three undocumented parameters on a non-trivial tool.

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 explains the mechanism (server-side context gathering plus ctx.sample()) and gives illustrative examples, but the actual capability is fuzzy: it says "no tools" yet takes an available_tools list and one example renames files, so it's unclear whether this analyzes files or performs file operations. It also never distinguishes itself from siblings like file_ops, dir_ops, or search_ops, which the examples reference.

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 compatibility note ("Compatible with Claude Desktop which supports basic sampling but not sampling.tools capability") and the two examples imply a usage context, and the Recovery section gives error-conditional guidance. However, there is no explicit rule for when to pick this tool over calling file_ops/search_ops directly, which is the key decision an agent faces given the siblings.

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