Crate nanocodex_tools 

Nanocodex Tools

Tool building blocks for OpenAI agents.

nanocodex-tools is useful without the Nanocodex agent loop. It provides the caller-defined Tool contract, tool macro, heterogeneous Tools registry, Code Mode runtime, standard workspace tools, and native MCP clients. The shared contract types are defined by nanocodex-oai-api and re-exported here so a tool implementation has one import surface.

Define and select tools

The definition is the single source of truth for a tool’s registry name. The macro derives its input and output schemas from the function:

use nanocodex_tools::{Tools, tool};

#[tool(
    name = "deployment_region",
    description = "Return the production region for a named service.",
    parallel = true
)]
async fn deployment_region(service: String) -> Result<String, std::io::Error> {
    Ok(format!("{service}: us-west-2"))
}

let tools = Tools::builder()
    .without_defaults()
    .tool(deployment_region)
    .build()?;

Macro tools execute serially unless parallel = true explicitly marks their local effects as safe to overlap. This does not change the provider wire protocol.

Implement Tool directly when execution needs ToolContext, freeform input, multimodal ToolOutput, or a custom definition:

use nanocodex_tools::{
    Tool, ToolContext, ToolDefinition, ToolInput, ToolOutput, ToolResult,
    contract::async_trait,
};
use serde_json::json;

struct DeploymentRegion;

#[async_trait]
impl Tool for DeploymentRegion {
    fn definition(&self) -> ToolDefinition {
        ToolDefinition::function(
            "deployment_region",
            "Return the production region for a named service.",
            json!({
                "type": "object",
                "properties": { "service": { "type": "string" } },
                "required": ["service"],
                "additionalProperties": false
            }),
        )
    }

    async fn execute(
        &self,
        input: ToolInput,
        _context: ToolContext<'_>,
    ) -> ToolResult {
        let input: serde_json::Value = input.decode_json()?;
        let service = input["service"].as_str().ok_or_else(|| {
            std::io::Error::new(
                std::io::ErrorKind::InvalidInput,
                "service must be a string",
            )
        })?;
        Ok(ToolOutput::text(format!("{service}: us-west-2")))
    }
}

Embed Code Mode in another host

hosted is the portable boundary for environments that own JavaScript execution outside Rust. Implement hosted::CodeModeHost and pass it to hosted::HostedTools; the adapter reuses the same execution, nested-call, notification, observer, and owned-context types as native Code Mode. The hosted module documentation includes a complete host implementation.

MCP is native and always available

MCP is not a feature flag. Native consumers configure stdio or Streamable HTTP servers and install the provider into the same registry:

use nanocodex_tools::{
    Tools,
    mcp::{Mcp, McpServer},
};

let mcp = Mcp::builder()
    .server(
        "company_docs",
        McpServer::stdio("company-docs-mcp").arg("--readonly"),
    )
    .build()?;

let tools = Tools::builder().provider(mcp).build()?;

Handshakes and discovery start with the owning runtime. mcp::Mcp exposes only the provider-native tool_search initially. Search results contain loadable MCP namespaces for direct model calls and also activate the matching definitions for Code Mode, keeping large catalogs out of the initial tool list.

Going lower level

The crate root intentionally contains only the normal registry path: Tools, ToolsBuilder, ToolsBuildError, Tool, tool, and the types required by the Tool methods.

• contract contains complete model-visible inputs, outputs, errors, and retained wire forms.
• hosted contains the portable application-owned Code Mode boundary.
• runtime contains the stateful per-agent executor, built-in connection configuration, and dynamic-provider contract.
• code_mode contains cell results, notifications, and nested-tool updates.
• mcp contains transport configuration, authentication, discovery, login, and runtime control.
• standard contains reusable standard-tool identities and the host-owned plan implementation.
• image contains prompt-image preparation and tool-output normalization.

Re-exports

pub use runtime::Tools;

pub use runtime::ToolsBuildError;Non-target_family=wasm

pub use runtime::ToolsBuilder;Non-target_family=wasm

Modules

code_modeNon-target_family=wasm

Code Mode execution results, notifications, and nested-tool observation.

contract

Model-visible tool definitions, inputs, outputs, and execution contracts.

hosted

Portable adapter for Code Mode runtimes owned by an embedding host.

imageNon-target_family=wasm

Prompt image preparation and model-output image normalization.

mcpNon-target_family=wasm

Background-handshaken MCP tools for Nanocodex Code Mode.

runtimeNon-target_family=wasm

Declarative tool selection and the stateful per-agent execution runtime.

standardNon-target_family=wasm

Stable identities and reusable implementations for standard workspace tools.

Structs

ToolContext

Read-only context for one tool invocation.

ToolOutput

Complete output of one tool invocation.

Enums

ToolDefinition

Model-visible tool definition carried by Responses Lite input.

ToolInput

Canonical input presented to function and freeform tools.

Traits

Tool

A caller-defined model-visible tool.

Type Aliases

ToolResult

Result returned by Tool::execute.

Attribute Macros

toolNon-target_family=wasm

Defines a typed JSON function tool from an async Rust function.