Idea bank: the content pipeline between scouting and publishing

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

The description discloses a key behavior: 'publish(idea_id=…) marks one used so the next session does not repeat it,' which aligns with the idempotentHint=true annotation and adds stateful context. However, it introduces 'publish' as if it were an action though the schema only allows add/list/drop, which is misleading. Other behaviors like what 'drop' does or whether 'add' is idempotent are not covered. No direct contradiction with annotations is present.

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 (33 words) and ends with a clear action list, which gives it some structure. However, it opens with the cryptic 'Free, local.' and inserts a function-like notation 'publish(idea_id=…)' that disrupts flow and wastes words on an irrelevant or mistaken concept. It is compact but not efficiently organized.

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?

With 7 parameters, no output schema, and minimal annotation coverage, the description carries heavy responsibility to explain inputs and side effects. It only addresses a few fields, omits crucial context like what 'drop' does, and incorrectly references a 'publish' workflow. The description is insufficient for an agent to correctly invoke all actions without additional guesswork.

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 only 14%, so the description must compensate, but it only loosely references source_url, format, and tags while omitting text and include_used entirely. Worse, it suggests a 'publish' action that does not exist in the schema, adding confusion rather than clarity. The description fails to meaningfully explain parameter roles or relationships beyond what the raw schema already shows.

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 indicates the tool parks and manages post ideas with source URL, format, and tags, and includes actions add/list/drop. However, the main verb is unclear and the mention of a non-existent 'publish(idea_id=…)' action confuses the purpose relative to the schema's enum. The title offers helpful context, but the description itself is vague and could apply to several different content-pipeline utilities.

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?

Usage is implied by the title 'content pipeline between scouting and publishing' rather than stated in the description. The description does not mention when to use this tool versus siblings like scout, publish, or draft_check, and gives no explicit when-to-use or when-not-to-use guidance. It is neither completely lacking nor helpful enough to distinguish from alternatives.

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