Overview The Tools API provides direct access to the tool registry in Shannon. You can list available tools, inspect their parameter schemas, and execute tools directly without going through a full task workflow.
Features
Tool discovery — browse all available tools with category filteringJSON Schema inspection — retrieve full parameter schemas for any toolDirect execution — invoke tools outside of agent workflowsDangerous tool blocking — hazardous tools are automatically hidden and blocked at the gateway levelUsage tracking — token consumption and cost are recorded per executionSession context — optionally bind execution to a session (sanitized to session_id and user_id only)
Security Model Shannon enforces a strict safety boundary around tools marked as dangerous:
List endpoint automatically applies exclude_dangerous=true — dangerous tools are never exposedGet and Execute endpoints return 403 Forbidden if the requested tool is marked dangerousTool metadata is cached in-memory for 5 minutes per gateway instance
The HTTP client timeout for tool execution is 120 seconds
Dangerous tools cannot be accessed through any public API endpoint. This restriction is enforced at the gateway level and cannot be overridden by clients.
List all available tools. Dangerous tools are automatically excluded.
curl http://localhost:8080/api/v1/tools \ -H "Authorization: Bearer <token>"
Query Parameters Parameter Type Required Description categorystring No Filter tools by category (e.g., "search", "code")
Example with Category Filter curl "http://localhost:8080/api/v1/tools?category=search" \ -H "Authorization: Bearer <token>"
Response [ { "name" : "web_search" , "description" : "Search the web for current information" , "category" : "search" , "version" : "1.0" , "parameters" : { "type" : "object" , "properties" : { "query" : { "type" : "string" , "description" : "Search query" }, "max_results" : { "type" : "integer" , "description" : "Maximum number of results" , "default" : 10 } }, "required" : [ "query" ] }, "timeout_seconds" : 30 , "cost_per_use" : 0.004 } ]
Get metadata and parameter schema for a specific tool.
curl http://localhost:8080/api/v1/tools/web_search \ -H "Authorization: Bearer <token>"
Path Parameters Parameter Type Required Description namestring Yes Tool name
Response { "name" : "web_search" , "description" : "Search the web for current information" , "category" : "search" , "version" : "1.0" , "parameters" : { "type" : "object" , "properties" : { "query" : { "type" : "string" , "description" : "Search query" }, "max_results" : { "type" : "integer" , "description" : "Maximum number of results" , "default" : 10 } }, "required" : [ "query" ] }, "timeout_seconds" : 30 , "cost_per_use" : 0.004 }
Execute a tool directly with the provided arguments.
curl -X POST http://localhost:8080/api/v1/tools/web_search/execute \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <token>" \ -d '{ "arguments": { "query": "latest AI news", "max_results": 5 }, "session_id": "optional-session-id" }'
Path Parameters Parameter Type Required Description namestring Yes Tool name
Request Body Field Type Required Description argumentsobject Yes Tool-specific arguments matching the tool’s parameter schema session_idstring No Session ID for context binding
When a session_id is provided, only session_id and user_id are passed to the tool. Other session fields such as tenant_id are stripped for security.
Response { "success" : true , "output" : { "results" : [ { "title" : "Major AI Breakthrough Announced" , "url" : "https://example.com/ai-news" , "snippet" : "Researchers announce a significant advancement in..." } ] }, "text" : "Found 5 results for 'latest AI news'" , "error" : null , "metadata" : { "source" : "searchapi" }, "execution_time_ms" : 1234 , "usage" : { "tokens" : 7500 , "cost_usd" : 0.004 } }
Response Fields Field Type Description successboolean Whether the execution completed successfully outputobject Structured output from the tool textstring Human-readable summary of the result errorstring | null Error message if execution failed metadataobject Tool-specific metadata (e.g., data source) execution_time_msinteger Execution duration in milliseconds usage.tokensinteger Token count for this execution usage.cost_usdnumber Estimated cost in USD
Usage is recorded asynchronously (fire-and-forget) to the token_usage table. Token counts are synthetic: max(100, int(cost_usd / 0.000002)).
Field Type Description namestring Tool identifier descriptionstring Human-readable description categorystring Tool category (e.g., "search", "code", "data") versionstring Tool version parametersobject (JSON Schema) Parameter schema for the tool timeout_secondsinteger Maximum execution time allowed cost_per_usenumber Estimated cost per invocation in USD
Error Responses Status Error Description 400 Bad request Missing tool name or invalid request body 401 Unauthorized Missing or invalid authentication 403 Forbidden Tool is marked as dangerous and cannot be accessed 404 Tool not found No tool with the specified name exists 502 Bad gateway LLM service (tool backend) is unavailable
All errors follow the standard format:
{ "error" : "error message here" }
Attempting to access a dangerous tool via Get or Execute returns:
{ "error" : "Tool not available via direct execution" }
Next Steps
Custom Tools Learn how to create and register custom tools
Agents Configure agents that use tools automatically
