Purpose
graph-tool-call is a tool retrieval and contract layer for LLM Agents. When the tool catalog is very large, semantic similarity search alone may find the target tool (for example refundOrder) but cannot satisfy that operation's dependency on input fields (for example order_id) that the user does not hold. In this case, the usable candidate set also needs to include operations that can produce that field. At the same time, sending every tool's schema to the model both wastes context and may reduce selection quality. graph-tool-call models retrieval as a graph problem that takes invocation contracts into account, rather than flat similarity search.
Main capabilities
- Deterministic ingestion from OpenAPI, GraphQL introspection, MCP tools, Python functions, and structured tool catalogs.
- Hybrid target retrieval, combining keywords, graph relationships, optional embeddings, and MCP annotation signals.
- Evidence-backed target selection and typed prerequisite dependency expansion.
- Model-facing catalogs use contract-projection schemas constrained by a token budget.
- Provides readiness status, failure information, and trace metadata for application-side diagnostics.
- Adapts to OpenAI, Anthropic, LangChain v1, MCP, Docker, and Kubernetes.
- Authentication, tenant policies, approvals, and product-specific execution logic still belong to the host application.
Usage
The project provides a "30-second experience" demo that runs the real retriever, deterministic target selector, typed dependency closure, and schema admission pipeline without a model, API key, or network calls.
The core search and graph packages use only the Python standard library, and optional integrations must be installed explicitly; the Python versions tested in CI are 3.10 to 3.14.
When ingesting OpenAPI, request and response schemas, parameter locations, content types, security requirements, links, examples, response wrappers, and typed consumes / produces contracts are preserved, supporting Swagger 2.0, OpenAPI 3.0, and OpenAPI 3.1.
Before exposing a tool set to an agent, you can first inspect its readiness status; the report provides stable readiness issue codes, semantic coverage, and edge quality, rather than a single opaqueScoring. Each adapter returns normalized ToolSchema objects, capability metadata, and structured "unsupported feature" diagnostics.
Hosted tools in OpenAI Responses (such as web search) are passed through as-is, and the same patch retains support for the legacy Chat Completions. Middleware intersects with the tools allowed by earlier permission or feature-flag middleware and does not reintroduce tools that have already been filtered out. The MCP endpoint is /mcp; HTTP deployments also expose /healthz and /readyz, and remote endpoints should remain private or be placed behind an authenticated gateway. The proxy accepts local stdio, SSE, and Streamable HTTP backends; in gateway mode it exposes search_tools, get_tool_schema, and call_backend_tool, and notifies clients with the corresponding capabilities when matching backend tools become visible.
Reproducible Evidence
The core metrics of the release are deliberately model-independent and small enough to be replayed in CI. On seven carefully selected e-commerce cases, adding typed producer expansion to the same selected target produced the corresponding effect; the case-level artifacts of v0.47.0 record fixture hashes, each expected target and producer, and the replay command. There are also observability artifacts for inspection: traces do not change engine inputs, can be replayed deterministically, redact secrets, explain each decision, and stay below the documented p95 collection cost threshold of 5ms/span. The project states that this result belongs to the engine regression suite, is not an overall estimate of LLM tool-calling accuracy, and does not constitute a state-of-the-art claim; larger-scale external comparisons, model-in-the-loop experiments, confidence intervals, and known weak cases are reported in Benchmark Results and the paper protocol.
Applicable Scenarios
Suitable for scenarios where an LLM Agent needs to reliably find target tools and their dependent tools in a large tool catalog (sources such as OpenAPI, MCP, GraphQL, Python functions, etc.) and where you want to control the schema size and token cost sent to the model.
Limitations
graph-tool-call is only responsible for the retrieval and contract layer; production adapters still need to handle user and service authentication, tenant authorization and approval policies, downstream secret and cookie handling, side-effect confirmation, cleanup and audit retention, provider and model lifecycleas well as the final response policy. Raw credentials should not be stored in graph artifacts, tool descriptions, trace records, or model-visible parameters.
