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

Annotations only say this is a non-readOnly, non-destructive, closed-world write; the description adds genuinely non-obvious behavior: dedupe by linking an already-listed feed to this node instead of duplicating, and public feeds being shared fleet-wide unless auto-approval is off. That is real added context beyond the annotations, though permission requirements and failure handling are still unstated.

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 scoping sentence is front-loaded and each subsequent sentence carries distinct information (immediate availability, auto-approval caveat, dedupe behavior). The inline return-shape bracket is the one piece that could be trimmed given an output schema exists.

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 mutating, non-destructive tool with a full input schema and an output schema, the description covers the pieces an agent can't infer: immediate searchability, dedupe-on-existing, and public-share/auto-approval behavior. The prose return shape duplicates the output schema and rejection causes remain vague, but nothing critical to invoking it correctly is missing.

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 coverage is 100% and the sources array already documents platform, source_kind, target, access_type and the 20-item cap, so the schema does the heavy lifting. The description adds no semantics for agent_name (separate tracking per name) or for how target formats map to source_kind, leaving the baseline 3.

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?

States a specific verb and resource ("Add feeds this node can read") and narrows scope to groups the person belongs to or searches they run. An agent can tell this registers existing feed sources rather than searching or discovering them, though it never names the closest sibling (submit_discovered_sources) to sharpen the boundary.

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?

"They are this node's to search right away: get_listening_assignment starts handing them out" gives useful sequencing context, and the auto-approval caveat hints at a precondition. But there is no explicit statement of when to use this over submit_discovered_sources, or what to do when a source is rejected.

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