content_plan_domain_intelligence

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

Annotations already flag destructiveHint=true, openWorldHint=true, idempotentHint=false, so the agent knows this is a mutating open-world action. The description adds only the scoping context (routes under JWT, tenant, company scope) but never discloses what executing the agent action will do, what state it may change, or what side effects to expect. No contradiction with annotations, but the behavioral burden is largely left to the annotation flags.

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 free of padding, with the Args section cleanly formatted and easy to scan. The opening sentence gets to the point immediately. It loses one point only because the brevity comes at the cost of substance in the other dimensions.

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 destructive, open-world agent action with no required parameters, an agent needs to know what the action will do, what kind of plan it returns, and what side effects to anticipate. The description answers none of these — it explains nothing about the behavior of plan_domain_intelligence beyond the routing mechanism. The presence of an output schema does not rescue this, since the agent cannot predict what kind of result to expect from a name alone.

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 carries the full burden for parameter meaning. It does provide minimal semantics ('message: Free-text objective', 'inputs: Optional JSON string of structured inputs'), which is more than the bare schema. However, it never explains what a well-formed objective looks like, what keys the inputs JSON should contain, or how the two parameters interact — insufficient compensation for a 0%-coverage schema.

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 opens with 'Run the content domain agent action `plan_domain_intelligence`' which largely restates the tool name rather than explaining what domain-intelligence planning actually accomplishes. The routing detail (dispatcher, JWT, tenant, company scope) is mechanical implementation, not purpose. It never says what output the action produces or what 'domain intelligence' means, so an agent cannot tell this apart from content_chat, content_generate_plan, or content_evolve_strategy.

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?

No guidance is given on when to use this tool versus any of the hundreds of siblings, including the similarly named coding_plan_domain_intelligence, commerce_plan_domain_intelligence, or the plain content_* planning tools. There are no exclusion criteria, no prerequisites, and no statement about when the dispatcher route is appropriate.

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