clear_cache

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

With no annotations provided, the description carries the full burden and does so well. It discloses that it removes every .png file from the cache directory, that it does nothing yet still reports success when the cache is disabled or the directory does not exist, and it lists the return fields (success, cleared_files, freed_bytes). This gives the agent a clear picture of side effects and edge cases.

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 concise and front-loaded: the first sentence states the action and result. It includes only necessary details about edge cases and return values, structured with Args/Returns sections that are easy to parse. No wasted words.

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?

This simple tool has no parameters and an output schema, so the description need not explain return structure in depth, yet it already does. It covers the action, edge cases, and the return payload (success, cleared_files, freed_bytes), making it fully complete for an agent to invoke 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?

The input schema has zero parameters, so the baseline is 4. The description mentions 'ctx: MCP context for logging' in the Args section, which adds context about logging but is not part of the user-facing schema; no additional parameter semantics are needed since there are no parameters to explain.

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 begins with a specific verb and object: 'Delete all cached render files and report freed space.' It clearly distinguishes this tool from siblings like render_single and export_model, which are about generating or exporting models, while this one is about cache maintenance.

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 does not explicitly state when to use this tool versus alternatives, relying instead on the self-explanatory name. It mentions edge cases (cache disabled or directory missing) but no guidance on when to invoke it (e.g., before a re-render) or when not to (e.g., if cached files are needed).

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