List, attach, or detach intel feeds on a policy

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

Annotations already declare destructiveHint=true and non-idempotent, and the description adds meaningful context: the read vs write permission split and the fact that customer feeds only affect endpoints in the owning org that have the feed attached. It stops short of describing what detach actually removes or whether attach replaces existing feeds.

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?

Three tightly packed sentences with zero waste: operations first, then scope, then permissions. Front-loaded and appropriately sized.

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?

Covers the actions, scope, and permission model for a multi-action mutation tool with no output schema. Still missing which parameters are mandatory per action (source_ids for attach, source_id for detach) and any return/effect details, leaving real gaps an agent must infer.

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?

With schema description coverage at only 50%, the description should compensate but does not: it never mentions policy_id, source_id (detach) or source_ids (attach), and the action enum values it alludes to are already in the schema. An agent must fall back entirely on the schema for parameter meaning.

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 names a specific resource (global/customer-owned intel feeds on a policy's current version) and enumerates all three operations (list, attach, detach). This lets an agent distinguish it from siblings like list_customer_intel_feeds or manage_customer_intel_feed without opening the schema.

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?

It states the permission condition that selects each action (list needs policies:read, attach/detach need policies:write) and notes the org-scoping behavior of customer feeds. However, it never names an alternative sibling (e.g., manage_customer_intel_feed) or an explicit when-not-to-use condition, so routing guidance is implicit rather than complete.

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