Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gumstack.com/llms.txt

Use this file to discover all available pages before exploring further.

Gumloop uses your tool’s return type to generate an output schema. This schema tells Gumloop what data your tool produces, enabling it to connect your tool’s output to other nodes in workflows. Without proper type annotations, these connections break.

​
Schema Mapping

Here’s how different return types translate to schemas:
Return typeGenerated schema
BaseModelSchema from model fields (recommended)
TypedDictSchema from typed keys
dict[str, T]Root-level dict schema
list[T], int, strWrapped as {"result": value}
No annotationNo schema — breaks Gumloop

​
Examples

See how different return types generate schemas that Gumloop can use. 
from pydantic import BaseModel, Field

class Issue(BaseModel):
    id: str
    title: str
    status: str = Field(description="Current status: open, closed, or in_progress")

@mcp.tool()
def get_issue(issue_id: str) -> Issue:
    """Fetch an issue by ID."""
    return Issue(id=issue_id, title="Bug report", status="open")
Generated schema: 
{
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "title": { "type": "string" },
    "status": {
      "type": "string",
      "description": "Current status: open, closed, or in_progress"
    }
  },
  "required": ["id", "title", "status"]
}

​
Lists

@mcp.tool()
def list_issues() -> list[Issue]:
    """List all issues."""
    return [Issue(...), Issue(...)]

​
Typed dicts

@mcp.tool()
def get_stats() -> dict[str, int]:
    """Get issue statistics."""
    return {"open": 5, "closed": 12}

​
Primitives

Primitives are wrapped in a result key: 
@mcp.tool()
def count_issues() -> int:
    """Count total issues."""
    return 17
Output: {"result": 17}

​
What to Avoid

These patterns will cause problems in Gumloop because they don’t generate usable schemas: 
# No return type — no schema generated
@mcp.tool()
def bad_tool():
    return {"data": "value"}

# Untyped dict — schema too generic
@mcp.tool()
def also_bad() -> dict:
    return {"data": "value"}
These tools work for direct MCP calls but break Gumloop workflows because there’s no schema for node connections.

​
Field Descriptions

Make your output easier to understand by adding descriptions to fields. These show up in Gumloop’s UI and help users know what each field contains: 
class SearchResult(BaseModel):
    url: str = Field(description="Full URL to the document")
    title: str = Field(description="Document title")
    score: float = Field(description="Relevance score from 0 to 1")