Skip to main content
KeyRing Docs
Documentation/Tools and Extensions

Tools and Extensions

Use the built-in KeyRing tool catalog in chat and agents, and understand how the desktop runtime translates tool definitions per provider.

Read time: 9 min read

Overview

KeyRing AI has a built-in local tool registry that the runtime can expose to supported models. Tool definitions are not hardcoded separately for each provider. Instead, the runtime normalizes the catalog into provider-native tool payloads before a request is sent.

What matters operationally

The same conceptual tool, such as web_search, may be sent to OpenAI, Anthropic, Gemini, Groq, or other providers in different native formats. KeyRing’s backend translation layer is what keeps that portable.

Where Tools Appear in the Product

  • Chatroom / Request Options: tool calling can be enabled for normal interactive queries.
  • Agent Builder: the Tools tab lets you whitelist the tools an agent can use.
  • Model Config: the Tools & Routing tab exposes lower-level routing and tool-related fields.

Built-in Tool Categories

CategoryRepresentative tools
Web & Internetweb_search, web_fetch, download_file
File Systemwrite_file, read_file, list_directory, create_directory, delete_file, move_file, copy_file, file_exists
Code Executionexecute_python, execute_shell, install_package
Image Generationgenerate_image, openai_image, openai_responses_image, openai_edit_image, xai_image, google_image
Systemget_system_info, get_datetime, open_url, open_file, clipboard_read, clipboard_write
Data Processingjson_parse, json_format, csv_read, csv_write, text_to_speech, echo_text

These are the built-in catalog groupings used by the runtime and by the Agent Builder tool picker.

Using Tools in Chat

1

Enable Tool Calling in Request Options

In the main workspace, tool access is controlled from the Request Options surface.

2

Submit a prompt that actually requires a tool

text
Find the latest FastAPI release notes, summarize any breaking changes,
and give me a migration checklist for an existing app.
3

Review the result with tool-assisted context

The runtime executes the tool, injects the result back into model context, and then the model continues the response.

Using Tools in Agents

Agent Builder exposes a Tools tab where you can select which tools the saved agent is allowed to use. That tool list is persisted with the agent profile and later passed into the runtime when the agent executes.

Agent tool controls

Tool behavior is also shaped by tool_choice and parallel_tool_callswhen the provider and execution path support those features.

Provider-native Translation

The runtime does not send one universal tool schema to every vendor. Instead, it uses a native translation layer before dispatch:

  • OpenAI can receive built-in native descriptors such as native web search payloads.
  • Anthropic receives its own provider-specific tool format for supported built-ins.
  • Gemini uses Google-native search grounding where applicable.
  • Groq handles web search differently and can strip that tool from the explicit payload for compound routing.
  • Other providers can fall back to standard function-style tool definitions when native built-ins are not available.

Tool Call Lifecycle

text
1) User prompt enters Chatroom or agent execution
2) Runtime builds provider-native tools from the shared registry
3) Model decides whether to call a tool
4) KeyRing validates and executes the local tool handler
5) Tool output is injected back into model context
6) Model returns its next or final response

Capability Variations by Provider

Not every provider supports the same tool-related controls. The capability layer tracks items such as:

  • whether parallel tool calls are supported
  • whether explicit tool choice modes are supported
  • whether a provider exposes native built-in tools such as search or code execution

Practical implication

A tool configuration that works cleanly on one provider may behave differently on another because the underlying provider contracts are different. KeyRing normalizes what it can, but it does not erase those differences.

Safety and Control

  • Tool availability is explicit, not implicitly always-on.
  • Agents can be restricted to selected tool subsets instead of full catalog access.
  • Iteration limits and runtime controls reduce runaway tool loops.
  • Agent execution traces help operators diagnose tool failures during agent runs.

Troubleshooting

Common tool issues

  • Tool is never used: confirm Tool Calling is enabled or the agent actually has that tool whitelisted.
  • Agent ignores tool preferences: check tool_choice and provider capability support.
  • Search behaves differently across providers: native search support varies by vendor and model path.
  • Execution fails mid-run: review the Agent Execution timeline and current provider/model status.

If tool behavior is tied to saved models or provider access, review Model Config and API Settings.