direct_add_feed

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It does indicate this is a write operation via 'WRITE:' and notes that allow_write must be true, which is a key behavioral requirement. However, it does not mention permissions, side effects, reversibility, return values, or what happens with dry_run, which is significant for a mutation tool. The description adds some context but leaves major behavioral aspects undisclosed.

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 remarkably concise, packing essential information into a single line. It is front-loaded with 'WRITE: feeds.add' immediately signaling the operation type. Every word contributes meaning, with no filler. The structure is highly efficient for an API-focused tool.

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?

Given the tool's complexity (7 parameters, no output schema, no annotations), the description is incomplete. It explains the primary input modes and business_type/source_type, but omits critical context such as what the tool returns, how dry_run behaves, whether the operation is reversible, and any preconditions. For a write operation with multiple parameters, this level of information is insufficient for an agent to fully understand the tool's behavior.

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 schema description coverage is very low (14%), with only allow_write documented. The description compensates by clarifying the semantics of key parameters: name + url for HTTP feeds, file_path for uploads, business_type with 'RETAIL|…' (indicating an enum-like set), source_type as URL|FILE, and the requirement for allow_write=true. This adds substantial meaning beyond the schema. However, dry_run is not mentioned in the description, so it does not cover all seven parameters.

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 clearly states this is a write operation for adding feeds ('WRITE: feeds.add'), specifying that it can use a URL or file_path. The verb 'add' is implicit in 'feeds.add' and the tool name, making it distinct from sibling tools like direct_delete_feeds or direct_list_feeds. However, it does not literally say 'adds a feed' in plain language, relying on the API method name.

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 some usage context by distinguishing the two input modes: 'name + url (HTTP feed) or file_path (upload)'. This implies when to use URL vs file upload. However, it does not explicitly state when to use this tool versus alternatives like direct_upload_advideo or direct_add_sitelinks, and no exclusions or conditions are mentioned. The guidance is minimal but not misleading.

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