SDKCustom tools

Custom tools

A custom tool gives the agent an action it does not have built in, such as querying your database or opening a ticket. A program can serve its own tools in-process over the stream-json channel, or add them through a separate MCP server. The built-in tools are chosen and narrowed with flags.

The Syntic Code SDK packages are not released yet. The options on this page are the ones the syntic command supports today.

Add a tool through an MCP server

An MCP server is a separate program that offers tools over the Model Context Protocol. Write the server in any language, then give its command to a run:

syntic -p "open a ticket for the failing build" --mcp-config tickets-server.json

The agent sees the server’s tools next to the built-in ones and calls them the same way. The full setup, including the config file format and the transports, is on MCP and on the MCP guide.

Serve a tool from your own program

A program that drives a run with --input-format stream-json --output-format stream-json can offer tools without starting a separate server process. Name one or more in-process servers in the initialize message:

{"subtype":"initialize","sdkMcpServers":["calc"]}

Before the first turn, Syntic Code sends MCP JSON-RPC messages for each named server to your program as mcp_message control requests, and reads your reply from mcp_response. It runs initialize and tools/list, then registers each tool as mcp__<server>__<tool>; a call to it arrives as tools/call. These tools go through the same permission checks as any MCP tool. A server that does not answer the handshake within 60 seconds is marked failed and its tools are left out, and the run goes on.

Limit the built-in tools

--tools limits the built-in tools to a list (comma or space separated). --tools "" turns every built-in tool off, and --tools default keeps them all. Remove single tools with --disallowed-tools, and pre-approve the ones a run needs with --allowed-tools. Deny rules win over allow rules.

syntic -p "summarise the changes in this folder" --tools "Read,Grep,Glob"
syntic -p "summarise the changes in this folder" --disallowed-tools "Write,Edit,Bash"

Change what a tool does

Hooks run around tool calls and can change them. A PreToolUse hook can change the input to a tool or refuse the call, and a PostToolUse hook can replace the tool’s output. Hooks are set in settings files, not in code. See the hooks reference for the events and their fields, and Hooks for programs for how a run reads their output.

Many tools

When a run has a large tool list (many MCP servers, or ENABLE_TOOL_SEARCH=true), only the core tools are sent in full. The others are named in the ToolSearch tool, and their schemas join the request once the agent asks for them. See Tool search.

If your tool is a service you already run, a small MCP server works with every run option above. If the tool lives in the program that drives the run, serve it in-process instead.