Agent Tools

In DYPAI, tools are endpoints. Any endpoint you've already built — a SQL query, a workflow that charges a card, a function that sends an email — can be flipped on as a tool. The agent reads its description, decides when to call it, and gets back whatever the endpoint returns.

This means you don't write "agent tools" separately from your app. The same list_products endpoint that your React frontend calls via useEndpoint() can be called by the agent on behalf of a conversation.

Turning an endpoint into a tool

Open the endpoint

Go to your endpoint's detail page in the dashboard.

Flip the Tool toggle

In the header, click the Tool toggle to enable it. A badge appears next to the endpoint's name.

Write a tool description

This is what the agent sees. Make it clear and specific — it's how the agent decides when to call the tool.

Good: "Search products by name, category, or price range. Returns up to 50 matching products with id, name, price, and stock."

Bad: "Products endpoint"

Define the input schema

Click Edit input schema and describe what parameters the tool accepts. This becomes the JSON schema the LLM uses to generate arguments.

Attach it to an agent

Open your agent endpoint, find the Tools field, and select the tool. Save.

Do it by asking

The MCP gives your AI assistant the ability to do all of this. Just say "Turn list_products and create_order into tools and attach them to my sales_assistant agent." The cloud MCP exposes 41 agent-facing tools — see the MCP reference.

Authoring via YAML / MCP

When you (or your AI assistant) define an agent in YAML or through the MCP, you reference tools by their endpoint name, not by UUID:

JavaScript

agent:
  provider: DYPAI Managed
  model: gpt-5-nano
  tools: [list_tasks, create_task]

The codec maps those names to the underlying tool_ids (UUIDs) automatically, and maps them back to names when it reads the workflow. Don't hand-write tool_ids with names in them — list the endpoint names under tools and let DYPAI resolve the IDs.

Input schemas

The input schema tells the LLM what arguments it can pass. DYPAI uses standard JSON Schema.

JavaScript

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search term for the product name"
    },
    "category": {
      "type": "string",
      "enum": ["electronics", "clothing", "books"],
      "description": "Optional category filter"
    },
    "max_price": {
      "type": "number",
      "description": "Maximum price in EUR"
    }
  },
  "required": ["query"]
}

Tips for good schemas:

Use description on every field. The LLM reads these.
Use enum to constrain choices when there's a fixed list — the LLM won't hallucinate values.
Mark required fields so the LLM knows what it must provide.
Keep it simple. A schema with 20 optional fields is usually a sign the tool should be split into two.

How the agent uses a tool

When the agent decides to call a tool:

The LLM generates the arguments matching the input schema.
DYPAI invokes the tool endpoint inside the same project — with the agent's user context (so ${current_user_id} and auth work as usual).
The endpoint returns its normal response.
That response is fed back to the LLM as a tool result.
The agent decides whether to call another tool, or produce the final answer.

This all happens inside a single execution. Your frontend sees one streaming response, not five separate requests.

Guardrails

Agents can do a lot of damage if they loop forever or call tools without limits. DYPAI has several guardrails built in, configurable per agent:

Parameter	Type	Description
`max_iterations`	`number (default 5)`	How many tool-call rounds the agent can run before giving up and returning what it has. Prevents infinite loops.
`tool_timeout`	`seconds (default 30)`	Per-tool timeout. If a tool takes longer, it's aborted and the agent gets an error it can recover from.
`Depth limit`	`automatic`	An agent tool cannot be called by another agent more than 3 levels deep. Prevents recursive tool chains from blowing up.
`Workflow stack tracking`	`automatic`	If a tool is already in the execution stack, it can't be called again in the same request. Prevents A → B → A loops.

Auth inside tools

Tools inherit the calling context. If a user with JWT auth chats with your agent:

Any tool the agent calls runs as that user
${current_user_id} in SQL resolves to the user's ID
Row-level security and role checks apply normally
A user can only ever act on their own data through the agent

This means you don't need separate "agent versions" of your endpoints. The endpoint you already wrote for GET /my-orders with JWT auth just works.

What endpoints make good tools?

Good

Query endpoints that return structured data (list, search, get). Simple mutations (create, update) with clear inputs. Idempotent actions the agent can safely retry.

Avoid

Endpoints with complex side effects (sending emails, charging cards) unless you really want the agent to do it autonomously. Endpoints without clear input/output schemas.

Destructive tools need confirmation

For tools that do destructive things — deleting, sending payments, sending messages — design them to require explicit confirmation fields (confirm: true) so the agent can't accidentally run them. Or keep them off agents entirely and let the user trigger them directly.

Limits


Tools per agent	No hard limit, but >10 starts hurting model accuracy
Tool description length	1024 chars
Tool timeout	1–120 seconds
Max iterations	1–20
Recursive depth	3 levels

Next steps

Models & Providers

Picking OpenAI vs Anthropic vs Gemini for tool-calling.

Memory

Keep conversation state across tool calls.

Agent Tools

Turning an endpoint into a tool

Open the endpoint

Go to your endpoint's detail page in the dashboard.

Flip the Tool toggle

In the header, click the Tool toggle to enable it. A badge appears next to the endpoint's name.

Write a tool description

This is what the agent sees. Make it clear and specific — it's how the agent decides when to call the tool.

Good: "Search products by name, category, or price range. Returns up to 50 matching products with id, name, price, and stock."

Bad: "Products endpoint"

Define the input schema

Click Edit input schema and describe what parameters the tool accepts. This becomes the JSON schema the LLM uses to generate arguments.

Attach it to an agent

Open your agent endpoint, find the Tools field, and select the tool. Save.

Do it by asking

Authoring via YAML / MCP

When you (or your AI assistant) define an agent in YAML or through the MCP, you reference tools by their endpoint name, not by UUID:

JavaScript

agent:
  provider: DYPAI Managed
  model: gpt-5-nano
  tools: [list_tasks, create_task]

Input schemas

The input schema tells the LLM what arguments it can pass. DYPAI uses standard JSON Schema.

JavaScript

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search term for the product name"
    },
    "category": {
      "type": "string",
      "enum": ["electronics", "clothing", "books"],
      "description": "Optional category filter"
    },
    "max_price": {
      "type": "number",
      "description": "Maximum price in EUR"
    }
  },
  "required": ["query"]
}

Tips for good schemas:

Use description on every field. The LLM reads these.
Use enum to constrain choices when there's a fixed list — the LLM won't hallucinate values.
Mark required fields so the LLM knows what it must provide.
Keep it simple. A schema with 20 optional fields is usually a sign the tool should be split into two.

How the agent uses a tool

When the agent decides to call a tool:

The LLM generates the arguments matching the input schema.
DYPAI invokes the tool endpoint inside the same project — with the agent's user context (so ${current_user_id} and auth work as usual).
The endpoint returns its normal response.
That response is fed back to the LLM as a tool result.
The agent decides whether to call another tool, or produce the final answer.

This all happens inside a single execution. Your frontend sees one streaming response, not five separate requests.

Guardrails

Agents can do a lot of damage if they loop forever or call tools without limits. DYPAI has several guardrails built in, configurable per agent:

Parameter	Type	Description
`max_iterations`	`number (default 5)`	How many tool-call rounds the agent can run before giving up and returning what it has. Prevents infinite loops.
`tool_timeout`	`seconds (default 30)`	Per-tool timeout. If a tool takes longer, it's aborted and the agent gets an error it can recover from.
`Depth limit`	`automatic`	An agent tool cannot be called by another agent more than 3 levels deep. Prevents recursive tool chains from blowing up.
`Workflow stack tracking`	`automatic`	If a tool is already in the execution stack, it can't be called again in the same request. Prevents A → B → A loops.

Auth inside tools

Tools inherit the calling context. If a user with JWT auth chats with your agent:

Any tool the agent calls runs as that user
${current_user_id} in SQL resolves to the user's ID
Row-level security and role checks apply normally
A user can only ever act on their own data through the agent

This means you don't need separate "agent versions" of your endpoints. The endpoint you already wrote for GET /my-orders with JWT auth just works.

What endpoints make good tools?

Good

Query endpoints that return structured data (list, search, get). Simple mutations (create, update) with clear inputs. Idempotent actions the agent can safely retry.

Avoid

Endpoints with complex side effects (sending emails, charging cards) unless you really want the agent to do it autonomously. Endpoints without clear input/output schemas.

Destructive tools need confirmation

Limits


Tools per agent	No hard limit, but >10 starts hurting model accuracy
Tool description length	1024 chars
Tool timeout	1–120 seconds
Max iterations	1–20
Recursive depth	3 levels