Toolsets

A toolset is a named collection of tool definitions that can be referenced by signature in resolution requests. Toolsets enable semantic caching, versioning, and efficient tool management.

Why Use Toolsets?

Instead of passing tool definitions inline with every request, you can:

1. Register tools once via the API
2. Reference by signature in subsequent requests
3. Benefit from semantic caching (inline tools bypass cache)
4. Version your tools using signature naming (e.g., home-v1, home-v2)
5. Update tools centrally without changing client code

Toolset Structure

{
  "name": "Home Automation",
  "signature": "home-v1",
  "description": "Smart home control tools",
  "tools": [
    {
      "name": "turn_on_lights",
      "description": "Turn on lights in a room",
      "parameters": {
        "type": "object",
        "properties": {
          "room": { "type": "string" }
        },
        "required": ["room"]
      }
    }
  ]
}

Signatures and Versioning

The signature is a unique identifier for your toolset. Use it to:

• Reference the toolset in /v1/resolve requests
• Version your tools (e.g., travel-v1, travel-v2)
• Maintain multiple toolsets for different contexts

{
  "query": "Turn on kitchen lights",
  "toolsets": ["home-v1"],
  "banks": []
}

Content Hashing

When you create or update a toolset, Intentgine generates a content hash based on the tool definitions. This hash is used for:

• Cache stability: Same tools = same cache keys
• Change detection: Updates invalidate relevant cache entries
• Deduplication: Identical toolsets share cache entries

Managing Toolsets

Toolsets are managed via the API. See the API Reference for full documentation.

Create a Toolset

curl -X POST https://api.intentgine.dev/v1/toolsets \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Home Automation",
    "signature": "home-v1",
    "tools": [...]
  }'

List Toolsets

curl https://api.intentgine.dev/v1/toolsets \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Update a Toolset

curl -X PUT https://api.intentgine.dev/v1/toolsets/home-v1 \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Home Automation",
    "tools": [...]
  }'

Delete a Toolset

curl -X DELETE https://api.intentgine.dev/v1/toolsets/home-v1 \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Best Practices

Organize by Context

Create separate toolsets for different domains:

home-v1       → Smart home controls
travel-v1     → Flight/hotel booking
finance-v1    → Banking operations

Version Strategically

Use versioning when making breaking changes:

• Minor updates (descriptions, new optional params): Update in place
• Breaking changes (renamed tools, removed params): Create new version

Keep Toolsets Focused

Smaller, focused toolsets perform better than large, generic ones:

✅ Good: home-lights-v1 (5 tools)
❌ Avoid: everything-v1 (50 tools)

Use with Memory Banks

Combine toolsets with memory banks for learned behavior:

{
  "query": "Turn on the lights",
  "toolsets": ["home-v1"],
  "banks": ["user-preferences"]
}

Quick Resolve vs Standard Resolve

Feature	/v1/resolve-quick	/v1/resolve
Tool input	Inline definitions	Toolset signatures
Semantic caching	❌ No	✅ Yes
Best for	Prototyping, testing	Production use
Performance	Slower (always compute)	Faster (cache hits)

Next Steps

• See the API Reference for toolset endpoints
• Learn about Memory Banks
• Explore Cache Optimization