create_mcp_integration

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

Annotations indicate this is a non-read, non-idempotent, non-destructive operation, and the description aligns with these hints. It adds meaningful context beyond the annotations: secret_mappings resolve protected values at runtime without storing them in the tool call, and workspace_id is needed for org admin keys. It also clarifies that this tool alone does not complete the MCP server setup, implying a multi-step 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 three sentences long, front-loads the core purpose, and every sentence carries distinct information: the action, auth handling, prerequisite, and next steps. There is no redundancy or filler, making it highly efficient.

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 creation tool with 9 parameters, nested objects (secret_mappings), and an output schema, the description covers the main workflow, auth security, and the necessary follow-up (create_mcp_server). It does not explain every enum value or optional parameter, but the schema covers those. The description is sufficiently complete for an agent to understand the tool's role and key constraints.

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?

The input schema has 100% description coverage, so the baseline is 3. The description adds extra meaning by explaining the relationship between custom_headers and secret_mappings (targeting configurations.custom_headers) and highlighting that secret_mappings avoid storing secrets in the call. It also specifies when workspace_id is required. This goes beyond mere schema enumeration, warranting a 4.

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 'Create a Portkey integration for an external MCP server URL', which clearly specifies the action and target resource. It also distinguishes itself from the sibling create_mcp_server by stating that after integration creation, one must call create_mcp_server to configure capabilities and access, making it unambiguous which tool does what.

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 explicitly instructs to use create_mcp_server after creating the integration, which sets the boundary between the two tools. It also notes that organization admin keys normally require workspace_id, providing a prerequisite. However, it does not explicitly enumerate cases where this tool should not be used or contrast it with other integration tools, so it falls short of a 5.

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