Skip to main content
Glama
zihin-ai

Zihin MCP Server

by zihin-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

create_schema

Creates a new schema for a Zihin agent, covering persona, API, workflow, skill, or MCP tool/resource configs. Use it to define agent behavior and integrations before creation.

Instructions

Cria um novo schema para um agente. O schema_data varia conforme o tipo:

  • persona_config: { editor_schema: { persona: { role, objective, tone, language, expertise, constraints, personality_traits, custom_guidelines } } }

  • api_config: { tool_definition, editor_schema } — ATENÇÃO: endpoint.name DEVE ser igual a tool_definition.name. editor_schema.api.timeout_ms (1000-120000, default 30000) é a fonte única do quanto esperar: alimenta o AbortSignal do fetch e o teto do executor (doc loop-review/34 F1).

  • workflow_config: { steps, transitions, conditions }

  • skill_config: { skill: { name, instructions, priority? } } — instruções comportamentais transversais

  • mcp_tool_config / mcp_resource_config: vínculo de tool/resource de MCP server (normalmente gerados pelo Builder) Triggers e CSPs NÃO são schemas: use create_trigger e create_csp.

WORKFLOW RECOMENDADO (evita erros de contrato): leia o resource zihin://schemas/{schema_type} (JSON Schema formal — o mesmo que o servidor valida), monte o schema_data, valide com validate_schema_data (dry-run), então crie.

Input Schema

NameRequiredDescriptionDefault
nameNoSem efeito (legado): schema não tem nome próprio. O nome que vale fica dentro de schema_data (ex.: tool_definition.name, skill.name).
agent_idYesUUID do agente
descriptionNoDescrição do schema
schema_dataYesDados do schema. Estrutura por tipo: PERSONA_CONFIG: { editor_schema: { persona: { role: string (obrigatório, minLength 3), objective: string (obrigatório, minLength 10), tone?: string, language?: string, expertise?: string[], constraints?: string[], personality_traits?: string[], custom_guidelines?: object, response_style?: { format?: string, rules?: string[], max_response_length?: number } } } } API_CONFIG: { tool_definition: { name: string (snake_case), description: string (min 20 chars), input_schema: { type: "object", required: string[], properties: { campo: { type, description } } } }, editor_schema: { api: { base_url: string (URL), endpoints: [{ name: string (DEVE ser igual a tool_definition.name), method: "GET"|"POST"|"PUT"|"DELETE", path: string }], auth?: { prefix: "Bearer"|"Basic", secret_ref: string } } } } REGRAS CRÍTICAS para API_CONFIG: 1. endpoint.name DEVE ser IGUAL a tool_definition.name (senão a tool falha no roteamento interno) 2. Path parameters usam formato ${variavel} (com cifrão). Ex: /resources/${resource_id}/items 3. Auth: usar "prefix" (não "type") no objeto auth. Ex: { "prefix": "Bearer", "secret_ref": "MY_TOKEN" }. Para Basic Auth, armazenar o secret já em base64 4. Para input_schema com objetos aninhados (ex: body complexo com sub-objetos), definir cada campo como type "object" com suas próprias properties CAMPOS DE TRANSFORMAÇÃO (opcionais em cada endpoint): - default_body: { "from": "noreply@x.com" } — valores fixos mergeados no body (LLM pode sobrescrever, exceto locked_fields) - locked_fields: ["from"] — campos do default_body que o LLM NÃO pode sobrescrever (enforcement server-side) - field_mapping: { "body": "html" } — renomeia campos do body antes de enviar (body vira html) - array_fields: ["to", "cc"] — garante que esses campos sejam sempre arrays - body_format: "array" — wrappa o body inteiro em array [body] (default: "object") - defaults_from_context: { "userId": "idUsuario" } — auto-inject de valores do webhookContext quando LLM não fornece WORKFLOW_CONFIG: { steps: [{ id, name, action }], transitions: [{ from, to, condition }], conditions?: array } SKILL_CONFIG: { skill: { name: string (minLength 3), instructions: string (minLength 50, markdown com regras comportamentais), priority?: integer (0-1000, default 0, maior = aparece primeiro no prompt) } } Contrato formal de cada tipo: resource zihin://schemas/{schema_type}. CSPs não são schemas — campos multi-agent (max_agent_depth, allowed_invoke_agents, child_timeout_ms) vivem em create_csp com policy_type=behavior.
schema_typeYesTipo do schema

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv2.2.2
    • changedInput schema / properties / name / description
      Previous value: -"Nome do schema"New value: +"Sem efeito (legado): schema não tem nome próprio. O nome que vale fica dentro de schema_data (ex.: tool_definition.name, skill.name)."
    • changedInput schema / properties / schema_data / description
      Previous value: -"Dados do schema. Estrutura por tipo:\n\nPERSONA_CONFIG: { editor_schema: { persona: { role: string (obrigatório, minLength 3), objective: string (obrigatório, minLength 10), tone?: string, language?: string, expertise?: string[], constraints?: string[], personality_traits?: string[], custom_guidelines?: object, response_style?: { format?: string, rules?: string[], max_response_length?: number } } } }\n\nAPI_CONFIG: { tool_definition: { name: string (snake_case), description: string (min 20 chars), input_schema: { type: \"object\", required: string[], properties: { campo: { type, description } } } }, editor_schema: { api: { base_url: string (URL), endpoints: [{ name: string (DEVE ser igual a tool_definition.name), method: \"GET\"|\"POST\"|\"PUT\"|\"DELETE\", path: string }], auth?: { prefix: \"Bearer\"|\"Basic\", secret_ref: string } } } }\n\nREGRAS CRÍTICAS para API_CONFIG:\n1. endpoint.name DEVE ser IGUAL a tool_definition.name (senão a tool falha no roteamento interno)\n2. Path parameters usam formato ${variavel} (com cifrão). Ex: /resources/${resource_id}/items\n3. Auth: usar \"prefix\" (não \"type\") no objeto auth. Ex: { \"prefix\": \"Bearer\", \"secret_ref\": \"MY_TOKEN\" }. Para Basic Auth, armazenar o secret já em base64\n4. Para input_schema com objetos aninhados (ex: body complexo com sub-objetos), definir cada campo como type \"object\" com suas próprias properties\n\nCAMPOS DE TRANSFORMAÇÃO (opcionais em cada endpoint):\n- default_body: { \"from\": \"noreply@x.com\" } — valores fixos mergeados no body (LLM pode sobrescrever, exceto locked_fields)\n- locked_fields: [\"from\"] — campos do default_body que o LLM NÃO pode sobrescrever (enforcement server-side)\n- field_mapping: { \"body\": \"html\" } — renomeia campos do body antes de enviar (body vira html)\n- array_fields: [\"to\", \"cc\"] — garante que esses campos sejam sempre arrays\n- body_format: \"array\" — wrappa o body inteiro em array [body] (default: \"object\")\n- defaults_from_context: { \"userId\": \"idUsuario\" } — auto-inject de valores do webhookContext quando LLM não fornece\n\nDB_CONFIG: { connection_id: uuid (de private_context_connections), tool_definition: { name, description, input_schema }, query_template: string (SQL com $1, $2...), parameter_mapping: string[] (campos do input na ordem dos $N), result_mapping?: { format: \"raw\"|\"table\"|\"summary\", max_rows?: number } }\n\nWORKFLOW_CONFIG: { steps: [{ id, name, action }], transitions: [{ from, to, condition }], conditions?: array }\n\nSKILL_CONFIG: { skill: { name: string (minLength 3), instructions: string (minLength 50, markdown com regras comportamentais), priority?: integer (0-1000, default 0, maior = aparece primeiro no prompt) } }\n\nContrato formal de cada tipo: resource zihin://schemas/{schema_type}. CSPs não são schemas — campos multi-agent (max_agent_depth, allowed_invoke_agents, child_timeout_ms) vivem em create_csp com policy_type=behavior."New value: +"Dados do schema. Estrutura por tipo:\n\nPERSONA_CONFIG: { editor_schema: { persona: { role: string (obrigatório, minLength 3), objective: string (obrigatório, minLength 10), tone?: string, language?: string, expertise?: string[], constraints?: string[], personality_traits?: string[], custom_guidelines?: object, response_style?: { format?: string, rules?: string[], max_response_length?: number } } } }\n\nAPI_CONFIG: { tool_definition: { name: string (snake_case), description: string (min 20 chars), input_schema: { type: \"object\", required: string[], properties: { campo: { type, description } } } }, editor_schema: { api: { base_url: string (URL), endpoints: [{ name: string (DEVE ser igual a tool_definition.name), method: \"GET\"|\"POST\"|\"PUT\"|\"DELETE\", path: string }], auth?: { prefix: \"Bearer\"|\"Basic\", secret_ref: string } } } }\n\nREGRAS CRÍTICAS para API_CONFIG:\n1. endpoint.name DEVE ser IGUAL a tool_definition.name (senão a tool falha no roteamento interno)\n2. Path parameters usam formato ${variavel} (com cifrão). Ex: /resources/${resource_id}/items\n3. Auth: usar \"prefix\" (não \"type\") no objeto auth. Ex: { \"prefix\": \"Bearer\", \"secret_ref\": \"MY_TOKEN\" }. Para Basic Auth, armazenar o secret já em base64\n4. Para input_schema com objetos aninhados (ex: body complexo com sub-objetos), definir cada campo como type \"object\" com suas próprias properties\n\nCAMPOS DE TRANSFORMAÇÃO (opcionais em cada endpoint):\n- default_body: { \"from\": \"noreply@x.com\" } — valores fixos mergeados no body (LLM pode sobrescrever, exceto locked_fields)\n- locked_fields: [\"from\"] — campos do default_body que o LLM NÃO pode sobrescrever (enforcement server-side)\n- field_mapping: { \"body\": \"html\" } — renomeia campos do body antes de enviar (body vira html)\n- array_fields: [\"to\", \"cc\"] — garante que esses campos sejam sempre arrays\n- body_format: \"array\" — wrappa o body inteiro em array [body] (default: \"object\")\n- defaults_from_context: { \"userId\": \"idUsuario\" } — auto-inject de valores do webhookContext quando LLM não fornece\n\nWORKFLOW_CONFIG: { steps: [{ id, name, action }], transitions: [{ from, to, condition }], conditions?: array }\n\nSKILL_CONFIG: { skill: { name: string (minLength 3), instructions: string (minLength 50, markdown com regras comportamentais), priority?: integer (0-1000, default 0, maior = aparece primeiro no prompt) } }\n\nContrato formal de cada tipo: resource zihin://schemas/{schema_type}. CSPs não são schemas — campos multi-agent (max_agent_depth, allowed_invoke_agents, child_timeout_ms) vivem em create_csp com policy_type=behavior."
    • changedInput schema / properties / schema_type / enum
      Previous value: -[
-  "persona_config",
-  "api_config",
-  "db_config",
-  "workflow_config",
-  "skill_config",
-  "mcp_tool_config",
-  "mcp_resource_config"
-]New value: +[
+  "persona_config",
+  "api_config",
+  "workflow_config",
+  "skill_config",
+  "mcp_tool_config",
+  "mcp_resource_config"
+]
    • changedInput schema / required
      Previous value: -[
-  "agent_id",
-  "name",
-  "schema_type",
-  "schema_data"
-]New value: +[
+  "agent_id",
+  "schema_type",
+  "schema_data"
+]
  2. First observedv0.1.0

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare non-readonly, non-idempotent, non-destructive, closed-world. The description adds real behavioral context beyond that: the cross-field enforcement rule (endpoint.name must equal tool_definition.name or the tool fails routing), that the server validates against a formal JSON Schema resource, and server-side enforcement of locked_fields. It does not discuss reversibility or auth requirements for the call itself, so it falls short of a 5.

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

Conciseness3/5

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

Front-loaded with purpose and type breakdown, which is good, but the text is very long and contains redundancy (the zihin://schemas/{schema_type} contract is stated twice) and internal jargon ('doc loop-review/34 F1') that gives an agent no usable signal. Much of the content earns its place given tool complexity, but the noise costs it.

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, nested-object, multi-type creation tool with no output schema, the description covers every variant, the critical API_CONFIG contract rules, transformation options, and a validation-first workflow. An agent has everything needed to construct a valid call without consulting external docs.

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

Parameters4/5

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning the schema does not: it warns that the top-level 'name' param is legacy with no effect, and documents the internal structure semantics of schema_data per type (required minLengths, transformation fields, defaults_from_context behavior). This is genuine added value over the schema.

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+resource ('Cria um novo schema para um agente') and enumerates the six schema_type values the tool accepts. It also explicitly distinguishes itself from siblings by declaring 'Triggers e CSPs NÃO são schemas: use create_trigger e create_csp,' so an agent can route correctly without opening other schemas.

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 an explicit when-to-use workflow ('leia o resource zihin://schemas/{schema_type}, monte o schema_data, valide com validate_schema_data (dry-run), então crie') and names the sibling tools that handle non-schema cases (create_trigger, create_csp). It even points to create_csp for multi-agent fields, leaving little to inference.

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

Deploy Server

Other Tools