Skip to main content
Glama
Sign In
SmartBear MCP server

SmartBear MCP server

Official
by SmartBear
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Swagger: Create Portal Product

swagger_create_portal_product
Idempotent

Create a new product in a specific Swagger portal from scratch or by duplicating an existing product, and configure its name, slug, visibility, and public access.

Instructions

Create a new product for a specific portal.

Toolset: Products

Parameters:

  • portalId (string) required: Portal UUID or subdomain - unique identifier for the portal instance

  • type (string) required: Product creation type - 'new' to create from scratch or 'copy' to duplicate an existing product

  • productId (string): Source product UUID to copy from - required when type is 'copy', specifies which existing product to duplicate. Omit when type is 'new'

  • name (string) required: Product display name - will be shown to users in the portal navigation and product listings (3-40 characters)

  • slug (string) required: URL-friendly identifier for the product - must be unique within the portal, used in URLs (e.g., 'my-api' becomes /my-api). 3-22 characters, lowercase, alphanumeric with hyphens, underscores, or dots

  • description (string): Product description - explains what the API/product does, shown in product listings and cards (max 110 characters)

  • public (boolean): Whether the product is publicly visible to all portal visitors - false means only authenticated users with appropriate roles can access it

  • visibility (enum): Whether the product is shown on the portal landing page - 'visible' shows it to everyone, 'hidden' hides it from everyone, 'conditional' shows it only to users who have access to the product (not allowed when the product is public)

Input Schema

NameRequiredDescriptionDefault
nameYesProduct display name - will be shown to users in the portal navigation and product listings (3-40 characters)
slugYesURL-friendly identifier for the product - must be unique within the portal, used in URLs (e.g., 'my-api' becomes /my-api). 3-22 characters, lowercase, alphanumeric with hyphens, underscores, or dots
typeYesProduct creation type - 'new' to create from scratch or 'copy' to duplicate an existing product
publicNoWhether the product is publicly visible to all portal visitors - false means only authenticated users with appropriate roles can access it
portalIdYesPortal UUID or subdomain - unique identifier for the portal instance
productIdNoSource product UUID to copy from - required when type is 'copy', specifies which existing product to duplicate. Omit when type is 'new'
visibilityNoWhether the product is shown on the portal landing page - 'visible' shows it to everyone, 'hidden' hides it from everyone, 'conditional' shows it only to users who have access to the product (not allowed when the product is public)
descriptionNoProduct description - explains what the API/product does, shown in product listings and cards (max 110 characters)

Output Schema

NameRequiredDescriptionDefault
idNo
urlNo
nameNo
slugNo
publicNo
portalIdNo
visibilityNo
descriptionNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.43.0
    • removedInput schema / properties / hidden
      Removed value: -{
-  "description": "Whether the product is hidden from the portal landing page navigation menus - useful for internal or draft products",
-  "type": "boolean"
-}
    • addedInput schema / properties / visibility
      Added value: +{
+  "description": "Whether the product is shown on the portal landing page - 'visible' shows it to everyone, 'hidden' hides it from everyone, 'conditional' shows it only to users who have access to the product (not allowed when the product is public)",
+  "enum": [
+    "visible",
+    "hidden",
+    "conditional"
+  ],
+  "type": "string"
+}
    • removedOutput schema / properties / hidden
      Removed value: -{
-  "type": "boolean"
-}
    • addedOutput schema / properties / visibility
      Added value: +{
+  "enum": [
+    "visible",
+    "hidden",
+    "conditional"
+  ],
+  "type": "string"
+}
  2. Addedv0.40.0
  3. Removedv0.34.0
  4. Changed1 schema field changedv0.30.0
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "description": {
+      "type": "string"
+    },
+    "hidden": {
+      "type": "boolean"
+    },
+    "id": {
+      "type": "string"
+    },
+    "name": {
+      "type": "string"
+    },
+    "portalId": {
+      "type": "string"
+    },
+    "public": {
+      "type": "boolean"
+    },
+    "slug": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}
  5. First observedv0.27.1

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral rules beyond that: slug must be unique within the portal, and visibility='conditional' is not permitted when public=true. It omits permission/auth requirements and side effects on the source product when copying, keeping it below a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and the toolset/parameter headings make it scannable. However, the bulk of the text is a verbatim restatement of schema descriptions, which is redundant for an agent that already receives the schema, so several lines do not earn their place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and all 8 parameters including the conditional productId requirement and enum constraints are covered. What remains unaddressed is authorization scope for creating a portal product and copy semantics, which is a modest gap for a creation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the description's parameter block reproduces the schema text nearly verbatim, so it adds essentially no meaning beyond the structured fields. Baseline 3 applies when the schema does all the semantic work; the only marginal value is consolidating the parameters in one scannable list.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource ("Create a new product") and scopes it to a portal. The verb cleanly separates it from siblings swagger_update_portal_product, swagger_delete_portal_product, swagger_get_portal_product, and swagger_list_portal_products without needing to name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear in-tool routing: type='new' creates from scratch, type='copy' duplicates, and productId is explicitly required for copy and to be omitted for new. It does not state when an agent should create a product at all versus updating one, nor any prerequisites, so it stops short of the explicit when/when-not/alternatives bar.

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

Deploy Server

Other Tools