Draft pausing a Reddit entity

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

The description explicitly discloses that this tool only creates a preview and does not execute the pause, which is important non-obvious behavior beyond the annotations. It clearly states that confirm_and_apply must be called with the plan_id to execute. This adds meaningful transparency about the two-phase workflow.

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 compact and front-loaded: it states the purpose, lists the key entity types, and gives the required follow-up action in just a few sentences. Every sentence adds necessary operational information with no filler.

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 that an output schema exists and annotations are present, the description covers the essential invocation context: entity types, entity_id sourcing, and the confirm_and_apply execution step. The only notable omission is ad_account_id semantics, but since it is optional with a default, this is a minor gap.

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 0%, so the description must compensate. It explains entity_type values and the source of entity_id, but ad_account_id is not mentioned at all. This is a gap, though the two required parameters receive adequate semantic guidance.

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 identifies the operation as 'Draft pausing' a Reddit entity and specifies the exact resource types: campaign, ad group, or ad. It also distinguishes this from a direct pause by stating it 'returns a PREVIEW' and that execution happens later via confirm_and_apply.

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 provides clear usage context: it names valid entity_type values, tells the agent to get entity_id from read tools, and explains the follow-up call to confirm_and_apply with the returned plan_id. It does not explicitly contrast with alternatives like pause_entity or enable_reddit_entity, but the workflow guidance is strong.

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