AI Agent Builder

This page is the canonical guide to building LLM agents with DevUtilities’ AI Agent Builder. Use the guided workflow above while you read, or jump to a topic below. Schemas, MCP JSON, prompts, and token counts stay in your browser — nothing is uploaded for inference.

AI Agent Builder is a client-side workshop for assembling production-ready agent configs: JSON Schema tools for OpenAI function calling, mcpServers validation for Cursor and Claude Desktop, system prompts, combined token budgets, and exportable artifacts for team handoff.

What you get

• Four workflow modes: full agent, function calling only, MCP setup, structured response
• Starter templates: Filesystem MCP, OpenAI function calling, structured classifier
• Example-JSON → JSON Schema inference with optional strict additionalProperties: false
• Local MCP lint with JSON-pointer errors and warnings
• Combined token budget across prompt, minified tools, and MCP JSON
• Exports: OpenAI tools JSON, response_format, MCP config, markdown summary, full bundle

Use this builder when

• You need OpenAI tools JSON and do not want to hand-write JSON Schema
• You are wiring Cursor or Claude Desktop MCP servers and want lint before paste
• You must prove an agent’s prompt + tools still fit a context window
• You want one persisted session that chains schema → MCP → prompt → export

Prefer a standalone tool when

• You only need deep encoding comparison or cost math → LLM Token Counter
• You only need one-off MCP lint without prompts → MCP Validator
• You only need schema inference from a sample → Structured Output Generator

Pick a mode before defining tools. Modes hide irrelevant steps so you do not fight empty panels.

First-time walkthrough for a full agent. Template shortcuts skip several of these steps.

1. Choose Full agent (or load the OpenAI function calling template).
2. On Define tools, add each tool with a clear name, description, and representative example JSON arguments.
3. Review inferred JSON Schema — enable strict mode for OpenAI structured outputs / strict tool calling.
4. Paste or edit mcpServers JSON if the agent will run inside Cursor or Claude Desktop; fix every error before continuing.
5. Write system instructions that tell the model when to call which tool and what never to invent.
6. Open Token budget, pick cl100k_base or o200k_base, and confirm the combined total fits your model.
7. Export OpenAI tools JSON for the API, MCP config for the desktop client, and a markdown summary for the team.
8. Optionally export the full bundle JSON so another engineer can reload the same session state later.

Problem: you need a customer-support agent that can look up weather and orders via OpenAI function calling, but hand-written JSON Schema keeps failing strict validation.

How this tool solves it

1. Select Function calling mode or load the OpenAI function calling template (weather + order lookup).
2. Edit example JSON so every field you need in production appears at least once — missing keys will not become required properties.
3. Enable strict mode so every object emits additionalProperties: false.
4. Tighten the system prompt: confirm order IDs, never invent tool results, keep replies concise.
5. Check the token budget under o200k_base if you deploy on GPT-4o.
6. Export OpenAI tools JSON and paste it into your Chat Completions or Responses API client.

Outcome: a strict, API-ready tools array plus a prompt that matches the schemas — without a separate schema editor.

Problem: Cursor or Claude Desktop rejects your mcp.json, or the filesystem server starts with the wrong directory and can see too much of the disk.

How this tool solves it

1. Choose MCP setup mode or load the Filesystem MCP template.
2. Replace /path/to/allowed/dir with an absolute path to the only directory the agent may touch.
3. Run validation — fix missing command/args, invalid URLs, and non-string env values.
4. Use placeholder env values (not production secrets) while linting in the browser.
5. Export validated mcpServers JSON into your Cursor or Claude Desktop config.
6. Add system instructions that require confirmation before destructive file operations.

Outcome: a linted MCP client config and a prompt that matches the server’s capabilities before you restart the desktop app.

Problem: you need the model to return sentiment, confidence, topics, and a short summary as JSON — free-form answers break your downstream parser.

How this tool solves it

1. Choose Structured response mode or load the structured classifier template.
2. Edit the example JSON to match the exact shape your pipeline expects.
3. Enable strict mode so undeclared keys are rejected at validation time.
4. Write a system prompt that forbids prose outside the JSON object.
5. Export response_format json_schema for OpenAI structured outputs.
6. Verify the token budget still leaves room for the input document you will classify.

Outcome: a single output schema you can drop into structured-output APIs with matching instructions.

Problem: after adding three tools and a long MCP config, the agent’s combined prompt no longer fits GPT-4o’s practical budget once chat history is included.

How this tool solves it

1. Open the Token budget step and note the combined total for prompt + minified tools + MCP JSON.
2. Shorten tool descriptions and remove unused example fields that inflate required schemas.
3. Move verbose policy text out of the always-on system prompt into on-demand retrieval.
4. If you only need deeper encoding math, copy the assembled payload into LLM Token Counter.
5. Re-export only after the budget shows comfortable headroom for history and completions.

Outcome: you catch overflow in the builder — not after the first production 400 error.

Example JSON must be strict JSON. Only keys present in the example become required properties. Nested objects and arrays infer types from the sample values.

Rules of thumb

• Include every field the model should be allowed to send — omission means “not required,” not “optional with a default.”
• Use realistic enums as string samples, then hand-edit the schema if you need an explicit enum array.
• Enable strict mode to emit additionalProperties: false on every object — recommended for OpenAI structured outputs and strict tool calling.
• Empty arrays infer weak item types — add at least one representative element.

Stdio servers need command and typically args. Remote servers need a valid http or https url. Env values must be strings. Errors block export confidence; warnings deserve a manual pass.

Common client envelopes

• Top-level key must be "mcpServers" for Cursor and Claude Desktop conventions
• Filesystem servers should use absolute allow-listed paths
• Prefer env placeholders while editing in the browser; inject real secrets only on the local machine

Token counts combine system prompt, minified tool schemas, and MCP JSON. Choose cl100k_base for GPT-4 / Claude approximation or o200k_base for GPT-4o. Counts use local tiktoken tables — no API calls.

• Treat the number as a floor: chat history and tool results add more at runtime
• Re-check after every schema or prompt edit
• Use LLM Token Counter when you need boundary maps or monthly cost cards on a custom payload

Symptoms: OpenAI rejects the tools payload, or the model cannot pass arguments that your app actually needs.

Why it happens

Strict schemas reject undeclared keys. If the example JSON omitted a field, it never became a property. If strict mode is off, OpenAI structured-output limits may still reject open objects.

Diagnose

Compare the inferred schema properties to the arguments your application sends. Check that strict mode is enabled when targeting OpenAI structured outputs.

Fixes

1. Add missing keys to the example JSON and regenerate the schema.
2. Enable strict mode so additionalProperties: false is consistent across nested objects.
3. Shorten unsupported constructs (deeply nested oneOf, exotic types) per OpenAI’s structured output limits.
4. Re-export tools JSON and retest with a single known-good argument payload.

Symptoms: validation errors on command/url, client fails to spawn the server, or remote transport never connects.

Why it happens

Stdio entries without command, remote entries without http(s) URLs, numeric env values, or wrong top-level keys break client parsers.

Diagnose

Read each lint error’s JSON pointer. Confirm the envelope uses mcpServers and that each server is either stdio (command) or remote (url), not a broken hybrid.

Fixes

1. Add command and args for stdio servers; quote all env values as strings.
2. Use http:// or https:// URLs for remote MCP transports.
3. Fix the top-level key name to mcpServers.
4. Re-run validation until errors are gone; triage warnings before shipping.

Symptoms: API keys appear in exported JSON, git diffs, or screenshots of the builder.

Why it happens

MCP env blocks are plain JSON. Pasting production secrets into a browser tool — even a local one — increases leak risk via clipboard, screen share, and accidental commits.

Diagnose

Search exports and the MCP panel for sk-, Bearer, or vendor key patterns. Check that committed configs only contain placeholders.

Fixes

1. Replace secrets with ${ENV_VAR} style placeholders in the builder.
2. Inject real values only in the local desktop client or deployment secret store.
3. Rotate any key that was pasted into chat, tickets, or shared screens.
4. Add a pre-commit secret scan for mcp.json and agent bundle files.

This workspace does not upload your config — but clipboard and git still can.

• Never commit API keys in MCP env blocks — use environment variable placeholders
• Use absolute, least-privilege paths for filesystem MCP servers
• Review token budget before adding large few-shot examples to production prompts
• Prefer strict schemas so tools cannot accept unexpected keys
• Treat exported bundles as sensitive if they contain internal tool names or infra hosts

• Start from a template, then delete tools you do not need — smaller schemas are cheaper and safer
• Name tools with clear verbs (lookup_order, get_weather) that match system-prompt instructions
• Keep one source of truth: export from this builder instead of maintaining divergent schema copies
• Re-validate MCP after every path or command change
• Document the token budget in the markdown export so reviewers see cost impact in PRs
• Use LLM Token Counter for deep encoding diffs; use this builder for the assembled agent