Skip to main content
Glama
Sign In

Convocore

by app.convocore.mcp
OverviewDiscussionsAdmin

create_agent_tool

Add an HTTP/API tool to a Convocore agent. Requires tool.name + tool.description. INPUTS — either (a) tool.variablesIds: ids of existing agent variables (create_agent_variable first), or (b) tool.fields[]: each entry needs key (the argument name — NOT "name"), type (string|number|boolean), in (body|query|header|path), plus description and required. REQUEST — simple tools: method + serverUrl (inputs are sent by their "in" location). Exact request shape: tool.httpRequest = { enabled: true, method, url, headers, query, bodyType: "json", bodyTemplate, bodyTemplateMode: "exact" }. In bodyTemplate/headers/query/url reference a variable with {{var:VARIABLE_ID}}; a value that is only that token keeps its number/boolean type. Fixed values are written literally. SECRETS — store an API key as an environment variable (create_agent_variable with isEnv: true; the value lives in defaultValue) and reference it with {{var:ID}}. Env variables must NOT be listed in variablesIds: they are resolved automatically and never shown to the model. An unfilled optional input sends its defaultValue; an input with no value and no default blocks the call with "Unresolved request values". By default the new tool is attached to the start node (nodes[].toolsIds) so the model can call it; pass attachToStartNode: false to skip. Verify with test_agent_tool_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": {
      "agentId": "<agentId>",
      "tool": "<tool>"
    },
    "name": "create_agent_tool"
  }
}

Input Schema

NameRequiredDescriptionDefault
toolYesTool definition: name, description, method, serverUrl, serverUrlSecret, variablesIds[] or fields[] ({key,type,in,description,required}), httpRequest{enabled,method,url,headers,query,bodyType,bodyTemplate,bodyTemplateMode}, channels[], etc.
agentIdYes
attachToStartNodeNoDefault true: adds the new tool id to the start node toolsIds so the agent can call it. A tool that is not in any node toolsIds is never offered to the model.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already flag non-readOnly, non-idempotent, and non-destructive; the description adds substantial behavioral context beyond that: how secrets/env vars are stored and hidden from the model, that unfilled optional inputs send defaultValue, and the exact 'Unresolved request values' failure. This is exactly the safety-relevant context annotations can't express.

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

Conciseness4/5

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

Front-loads the purpose and the required fields, then organizes the rest under INPUTS / REQUEST / SECRETS labels. It's dense and long, but nearly every sentence carries actionable detail; slightly more volume than strictly necessary for a single write tool.

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 a complex tool with nested objects and no output schema, it covers the critical ambiguity (variables vs fields), the request-building mechanism, secret handling, and attachment behavior. An agent could call it correctly without guessing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 67% schema coverage, the description does heavy lifting: it spells out the httpRequest object shape, the {{var:ID}} reference syntax, number/boolean type preservation for token-only values, the fields[] entry contract (key, type, in, description, required), and the attachToStartNode default. Far more than the schema provides.

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?

States a specific verb and resource: 'Add an HTTP/API tool to a Convocore agent', and contrasts naturally with create_agent_variable and update_agent_tool siblings. An agent can tell this creates a new tool definition rather than a variable.

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?

Gives explicit prerequisites ('create_agent_variable first'), the two mutually exclusive input modes (variablesIds vs fields[]), and a verification path ('Verify with test_agent_tool_request'). It also names the opt-out condition (attachToStartNode: false).

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

All Convocore toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources