create_integration

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

The description discloses that the API key is write-only and will be masked on retrieval via get_integration, a behavioral trait beyond what annotations provide. It also specifies the return value (id and slug). No contradictions with annotations.

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 three concise sentences, front-loaded with the primary purpose, and every sentence contributes essential information. No redundant or vague content.

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 the complexity of 15 parameters and the existence of an output schema, the description covers the core purpose, key behavioral notes, provider-specific requirements, and follow-up steps. It is complete for effective tool selection and invocation.

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?

While the input schema has 100% coverage, the description adds value by explaining that ai_provider_id takes identifiers like 'openai' and 'anthropic', and that some backends (azure-openai, aws-bedrock, vertex-ai) require provider-specific fields. This context helps the agent understand parameter selection beyond the schema descriptions.

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 states the tool creates an org-level provider integration that stores API keys and serves as the basis for workspace providers via create_provider. It distinguishes itself from sibling tools like create_provider by specifying the org-level scope.

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 provides explicit usage guidance: create the integration first, then use create_provider for workspace providers, and provision models/workspaces with update_integration_models and update_integration_workspaces. It also notes provider-specific fields for certain backends.

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