flowforge-mcp

flowforge_api_request

Destructive

Call any documented FlowForge External API endpoint directly for operations without a curated tool or exact body control; destructive and side-effect calls return a dry-run preview until confirmed.

Instructions

Call any documented FlowForge External API endpoint directly.

Use for operations without a curated tool (characters, roles, vapi-import, voice preview, MCP-server attachment, analytics variants, ...) or when you need exact control of the body. Auth, host, HTTPS-safe redirects and read retries are handled for you.

Safety: unknown endpoints are refused (unless allow_undocumented), and DELETEs plus side-effect operations return a dry-run preview until called again with confirm=true. Never auto-confirm calls that dial real phones or spend money without the user's go-ahead.

Returns: JSON {"status", "request_id", "endpoint", "body"}. Non-2xx responses are returned the same way with an error summary (not raised), so you can read the 422 field errors and fix the request.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "params": "<params>"
    },
    "name": "flowforge_api_request"
  }
}

Input Schema

Name	Required	Description	Default
`params`	Yes

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Nov 6, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds substantive behavior the annotations cannot express: auth/host/redirect/retry handling, refusal of unknown endpoints unless allow_undocumented, and the two-step dry-run-then-confirm gate for DELETEs and side-effect operations. It also discloses that non-2xx responses come back as data rather than exceptions, which changes how the agent should handle failures. The only gap is that it does not say whether a dry-run preview expires or must be repeated within a session.

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

Conciseness5/5

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

Front-loaded with purpose, then usage, then safety, then a clearly delimited Returns block. Every sentence contributes a distinct fact (safety gate, error-as-data semantics, undocumented-endpoint escape hatch); nothing is padding or restated from annotations.

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

Completeness5/5

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

For an open-world, destructive, untyped-body tool this is close to the right amount of information: it covers auth, retries, endpoint validation, the confirmation protocol, and error surfacing. An output schema exists so return values need not be detailed, yet the brief Returns line usefully clarifies that errors are not raised, which is the one non-obvious contract detail an agent needs.

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?

Reported schema description coverage is 0%, so the description is expected to compensate; it partially does by explaining the confirm gate (dry-run until confirm=true) and the allow_undocumented escape hatch, both of which are behavioral rather than restatements. However it adds nothing about path formatting, query encoding, or max_chars truncation, which are the parameters an agent is most likely to get wrong on a raw-API tool. The schema's own per-field text carries most of that weight, so this lands at adequate rather than strong.

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 line names a specific verb and resource ('Call any documented FlowForge External API endpoint directly') and immediately positions it as the escape hatch for operations without a curated tool, listing concrete examples (characters, roles, vapi-import, voice preview, MCP-server attachment). An agent can tell this apart from every curated sibling in the list without opening a schema.

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

Usage Guidelines5/5

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

It gives an explicit positive condition ('operations without a curated tool' or 'when you need exact control of the body') and an explicit negative/guard condition ('Never auto-confirm calls that dial real phones or spend money without the user's go-ahead'). It also routes the agent to flowforge_api_reference for schema lookup before building a body, so the alternative tool is named.

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

Deploy Server