Clear Audiobookshelf cache by triggering a cache purge request. Use this to free up storage or reset cached data.
Create or act on cache purge.
POST /api/cache/purge
Args: body: Request payload. Read the matching GET or the /schema endpoint first to see the fields this resource expects.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes |
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Changes observed during successful MCP inspections.
v1.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true, readOnlyHint=false, and destructiveHint=false, but the description adds no behavioral context about what a purge does, whether it invalidates immediately, what gets cleared, or any side effects. It does not contradict the annotations, but it also provides no additional transparency.
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 short and front-loaded, with no fluff. The endpoint is stated clearly and the parameter guidance is compact, though the opening line is vague and could have been more informative.
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?
For a tool with one loosely typed body parameter, no documented fields, and a nearby sibling with a similar name, the description is too incomplete. It does not explain the purpose, effects, required fields, or relationship to create_cache_items_purge, so an agent would struggle to invoke it 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 description coverage is 0%, so the description must compensate. It identifies 'body' as the request payload and points to the GET/schema endpoint for fields, which is a small hint, but it does not explain any actual body fields or their meaning. The schema's additionalProperties:true leaves the agent almost entirely unguided.
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 says 'Create or act on cache purge,' which is vague and largely restates the tool name. The endpoint line 'POST /api/cache/purge' identifies the route but does not clarify what the operation actually does or what 'act on' means.
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 is given about when to use this tool versus alternatives such as create_cache_items_purge. The advice to 'Read the matching GET or the /schema endpoint first' concerns how to discover fields, not when to select this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.