knowledge_base

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

No annotations are provided, so the description carries the full burden for behavioral disclosure. It says 'manage' but does not explain that write/delete will modify or remove files, whether overwrites occur, or whether there are auth/destructive implications. The only added context is the .md file description and a workflow rule, neither of which is a tool behavior.

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?

Two sentences with the core resource and purpose front-loaded before the workflow directive. No wasted words, and the example-free style keeps it scannable. Slightly more detail on write/delete behavior would be useful but not at the cost of brevity.

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 description covers the central use case—reading KB context before clip work—and the schema fully documents parameters. However, with no output schema and no annotations, the agent is left to infer the return value of read_all/list/read and the effects of write/delete. This is a moderate completeness gap for a tool with five actions.

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 100%, so the parameter meanings are already well-defined: 'action' enum, 'content' for write, and 'filename' with an example. The description adds only the context that files are markdown and the workflow reminder. Baseline 3 is appropriate because the schema carries the load.

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?

Clear verb+resource pair: 'read or manage the podcli knowledge base.' The description adds a concrete characterization ('.md files that provide context about the podcast') and connects to clips, making the resource's role understandable. It doesn't explicitly contrast with siblings, but the KB is distinct enough from clip-oriented tools.

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 gives an explicit trigger: 'Always read the knowledge base before suggesting or creating clips.' This tells an agent when the tool is a required preliminary step. It doesn't discuss alternatives or when to avoid the tool, but the directive is actionable.

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