Tool Operations

Beyond creation and execution, appgrammar provides 30+ tools for composing, transforming, analyzing, and discovering appgrammars. These tools are organized by the 7 axioms — see that page for what each tool does and why.

This guide covers how tool operations work: the multi-turn protocol, lifecycle, and practical workflows.

Multi-Turn Protocol

Most tool operations are multi-turn. The first call returns a prompt (for the agent to run on its LLM) and a single-use token. The agent processes the prompt, then submits structured output to advance the operation.

Via MCP

1. Call the tool (e.g. appgrammar_breed) with source appgrammar IDs
2. Receive a prompt, expected output schema, and a token
3. Run the prompt on your LLM
4. Submit the result via appgrammar_tool_submit with the token
5. Repeat until the operation returns a final result

Via REST API

# 1. Start the operation
curl -X POST https://appgrammar.com/api/tools/operations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_type": "breed",
    "source_appgrammar_ids": ["ID_A", "ID_B"],
    "params": {}
  }'

# 2. Submit each step
curl -X POST https://appgrammar.com/api/tools/operations/OPERATION_ID/submit \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "STEP_TOKEN",
    "submission": { "...structured output..." }
  }'

# 3. Check status at any time
curl https://appgrammar.com/api/tools/operations/OPERATION_ID \
  -H "Authorization: Bearer $TOKEN"

# 4. Cancel if needed
curl -X POST https://appgrammar.com/api/tools/operations/OPERATION_ID/cancel \
  -H "Authorization: Bearer $TOKEN"

Token Lifecycle

• Tokens are single-use UUIDs — each token can only be used once
• Tokens expire after 30 minutes
• If a submission fails validation, a retry_token is provided with remaining retries
• Each successful submission returns the next step's token (or a final result)

Operation States

Status	Description
initialized	Operation created, waiting for first submission
in_progress	At least one step submitted, more steps remaining
completed	All steps done, result appgrammar(s) created
cancelled	Cancelled by the user
expired	Token expired before completion

Single-Turn Tools

Some tools complete in one call with no submission needed:

• appgrammar_fork — creates a copy immediately
• appgrammar_search — returns registry results
• appgrammar_start / appgrammar_next — execution step delivery
• appgrammar_status — execution progress check
• appgrammar_broadcast — sends notifications

The Update Tool

appgrammar_update closes the feedback loop between the built application and the blueprint. After iterating on your codebase, the agent compares reality against the blueprint, identifies structural changes (modules added, removed, or updated), and submits a structured changeset.

• Owner: updates the blueprint in place with an automatic version snapshot
• Non-owner or mode: "copy": creates a fork with the changes applied

See Keeping the Blueprint in Sync for setup instructions including auto-sync hooks.

Available Tool Types

For the full list of tools organized by axiom with descriptions, see The 7 Axioms. For parameter-level API reference, see MCP Tools Reference.