Tool Naming and Compatibility

How DataGrout resolves tool names across different clients and calling conventions

DataGrout tools use a structured canonical format, but many AI clients (Claude, ChatGPT, n8n, LangChain, Cursor, etc.) restrict function names to ^[a-zA-Z0-9_-]{1,64}$ — no @ or / allowed. DataGrout handles this automatically, so you can call tools using whichever format your client supports.

Canonical format

Every tool has a canonical name:

integration@version/toolsuite.tool@version

Examples:

• data-grout@1/discovery.discover@1
• salesforce@1/get_leads@1
• quickbooks@1/find_recent_invoices@1
• data-grout@1/warden.ensemble@1

Rules:

• Lowercase, kebab-case for multi-word integrations
• Dots separate tool suites from tool names (prism.refract, warden.canary)
• Versions are integers after @ (currently @1 for all tools)

If your client supports arbitrary function names, you can use canonical names directly.

OpenAI-compatible format

For clients that restrict function names to letters, numbers, underscores, and hyphens, DataGrout generates a flat name by stripping versions and replacing / and . with underscores:

When you call tools/list, each tool descriptor includes both names:

{
  "name": "data-grout@1/warden.ensemble@1",
  "openai_name": "data-grout_warden_ensemble",
  "description": "Runs the full Warden ensemble...",
  "inputSchema": { ... }
}

Automatic client detection

DataGrout detects clients that need OpenAI-compatible names and transforms tools/list responses automatically. Known clients include:

• Claude Desktop, Claude AI
• ChatGPT, OpenAI API clients
• n8n workflow automation
• LangChain, LlamaIndex
• Cursor, Continue, Cline, Windsurf
• mcp-remote transport library

When detected, tools/list returns openai_name as the primary name field and preserves the original in canonical_name.

Forcing OpenAI mode

If auto-detection doesn’t work for your client, you can force it:

• Set the header x-openai-mode: true on your connection

Calling tools with flat names

When you make a tools/call with a flat name (no /), DataGrout resolves it back to canonical form through a multi-step fallback chain:

1. Descriptor match — scans the server’s tool list for a matching openai_name or cursor_name
2. Prefix-based reversal — splits the flat name on known integration prefixes (salesforce, quickbooks, data-grout, hubspot, stripe, github, slack, google, jira, notion, etc.) and reconstructs the canonical form
3. Passthrough — if no match is found, the name is used as-is

This means you can call tools using any of these equivalent forms:

// Canonical
{ "method": "tools/call", "params": { "name": "data-grout@1/warden.canary@1", "arguments": { ... } } }

// OpenAI-compatible
{ "method": "tools/call", "params": { "name": "data-grout_warden_canary", "arguments": { ... } } }

Both resolve to the same tool.

Version handling

Versions are flexible on input:

If you omit versions, @1 is assumed. The @v1 prefix form and @latest tag are also accepted and normalized. Canonical names are case-insensitive — Salesforce@1/GET_LEADS@1 resolves identically.

Transport encoding

Some transports cannot carry @ or / in tool names. DataGrout accepts two encoding schemes:

These are decoded before normalization, so they work seamlessly with all resolution paths.

Collision handling

When multiple tools produce the same OpenAI-compatible name (e.g., two integrations with tools that differ only by version), DataGrout appends a numeric suffix to disambiguate:

salesforce_create_lead    → salesforce@1/create_lead@1
salesforce_create_lead_2  → salesforce@2/create_lead@1

The dedup suffix is stripped during resolution, so calling salesforce_create_lead_2 correctly resolves to the second variant.

Summary

All formats resolve to the same canonical tool and produce identical results. Use whichever your client supports.

Related

• Tools Reference — Full list of DataGrout core tools
• Authentication — How to connect your client
• Conduit SDK — Drop-in SDK for Python, TypeScript, and Rust