clear_domain_cache

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

No annotations are provided, so the description carries full burden of behavioral disclosure. The description states the action (clear cache) but doesn't disclose side effects—does this invalidate domain checks for all domains? Does it require privileges? Is there any persistence impact? With zero annotations, this is under-specified for a mutating tool.

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?

A single clear sentence with no waste. It's appropriately brief for a zero-parameter tool. Could arguably benefit from one additional clause explaining when to invoke, but the current form is efficient.

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?

While an output schema exists, this is a mutating cache-clearing operation with no annotations and no usage guidance. For a tool with side effects, additional context (side effects, prerequisites, frequency of need) would meaningfully improve agent decision-making. The current description is bare-minimum.

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?

There are 0 parameters, and schema description coverage is 100%. The baseline for 0 params is 4 since there is nothing for the description to compensate for. The description adds nothing beyond what's needed, and none is required.

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 states it clears the in-memory domain check cache, giving a clear verb and resource (clear + cache). However, it doesn't distinguish clearly from siblings—given sibling tools are check_domain, domain_info, etc., the cache-clearing purpose is reasonably distinct, but the description doesn't explain what the cache is used for or why an agent might want to clear it.

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?

No guidance on when to use this tool. It doesn't explain scenarios (e.g., after updates to domain rules, when stale check results are observed) or when NOT to use it. For a cache-clearing maintenance tool with no schema parameters, usage context is entirely absent.

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