document_intelligence_create_marketing_collateral

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

Annotations already declare this is mutating, destructive, non-idempotent, and open-world. The description adds useful context about JWT/tenant/company scoping and dispatcher routing, which goes beyond the annotations. However, it does not clarify actual output behavior, persistence, or side effects beyond what the action name implies, so it adds only moderate value.

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 short and mostly front-loaded: it states the core operation first, adds routing context, and then lists both parameters in a compact Args block. The opening sentence is somewhat redundant with the tool name, but the overall size is appropriate and there is 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?

For a generic dispatcher-style action with only 'message' and opaque 'inputs', the description does not provide enough to ensure correct invocation. There is no guidance on what structured inputs should look like, no expected behavior, and no differentiation from several similar document_intelligence creation tools. The presence of an output schema reduces the need for return-value documentation, but the input and selection gaps remain substantial.

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 does explain that 'message' is a free-text objective and that 'inputs' is an optional JSON string, which is more than the bare schema provides. Yet it does not describe the expected JSON structure, accepted keys, or examples, leaving a significant gap for an agent trying to invoke the action correctly.

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 uses an action verb ('Run') and identifies the resource (creating marketing collateral through the document_intelligence domain agent). However, it does not differentiate this from closely named siblings like document_intelligence_create_marketing_document or document_intelligence_create_sales_collateral, so the precise scope of 'marketing collateral' is left to inference.

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 no explicit guidance on when to choose this tool over alternatives, nor does it mention any exclusion criteria. It only states that it routes through the domain-agent dispatcher, which is about mechanics, not selection. Given the huge sibling set of document_intelligence creation tools, this leaves the agent without decision support.

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