> ## Documentation Index > Fetch the complete documentation index at: https://docs.orq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve tool > Retrieves a tool by id. **Related guide**: Tools guide. See the [Tools guide](/ai-studio/ai-engineering/create-tools) for a walkthrough with examples. ## OpenAPI ````yaml get /v2/tools/{tool_id} openapi: 3.1.0 info: title: orq.ai API version: '2.0' description: orq.ai API documentation servers: - url: https://my.orq.ai security: - ApiKey: [] tags: - name: Chunking description: Split text into smaller chunks for retrieval and generation workflows. - name: File Systems description: >- Create and manage persistent file systems that agents and MCP clients read from and write to. - name: Knowledge Bases description: Create and manage knowledge bases used by agents and retrieval workflows. - name: Memory Stores description: Create and manage memory stores, memories, and memory documents. - name: Evals description: Run an evaluator against a conversation and its result - name: Logs description: >- OpenTelemetry log query API. Search, filter, aggregate, and facet log records ingested via OTLP. - name: Reporting description: >- GenAI reporting API over canonical analytics rollups. Accepts a metric name, time range, grain, group-by, and filters; returns a typed time series and optional totals. - name: Traces description: >- Query and inspect ingested trace data: search trace summaries, aggregate metrics, and read individual traces and their spans. - description: List models available through the AI Router. name: Models - name: Policies - name: Alerts description: >- Alerts evaluate a Reporting API metric on a fixed interval and fire notifications through notifiers when the value breaches a threshold. Each breach opens a trigger that tracks the incident until the value recovers. - name: Annotation Queues description: Annotation queues collect spans for human review. - name: API keys description: >- API keys authenticate programmatic access to the workspace. They expose opaque tokens, per-domain access grants, and budget and rate-limit constraints. - name: Audit Logs description: Audit logs record workspace entity changes and access-relevant events. - name: Budgets description: >- Budgets govern spend, token usage, and request rate across six scopes: workspace, project, identity, API key, provider, and model. Every applicable budget is enforced, and the most restrictive limit applies per dimension. - name: Files description: File upload and retrieval operations. - name: Guardrail Rules description: >- Guardrail Rules conditionally enforce evaluators and plugins for AI Gateway traffic. Rules may be scoped to a project or the whole workspace. - name: Hub description: Hub items are reusable templates available to a workspace. - name: Identities description: >- Identities represent end users from your system for usage and engagement tracking. - name: Management keys description: >- Management keys are workspace-scoped credentials that authenticate programmatic access to workspace administration surfaces (API keys, budgets). Unlike project-scoped API keys, a management key always operates at the workspace level. - name: MCP Gateway description: >- Register upstream MCP servers, discover and sync their tools, and assemble gateways that expose a curated tool surface to MCP clients. - name: Model Catalog description: >- Browse the orq.ai model catalog: every model orq offers, across every provider, with pricing, capabilities and benchmark data. List endpoints only return models that are not deprecated. This API is public, requires no authentication, and is rate limited to 120 requests per minute per IP. Responses carry a 5-minute cache-control max-age. - name: Notifiers description: Notifier destinations used to send delivery and workflow notifications. - name: Projects description: Projects organize resources within a workspace - name: Routing Rules description: >- Routing Rules conditionally select models and enforce request plugins for AI Gateway traffic. Rules are evaluated by ascending priority and may be scoped to a project or the whole workspace. - name: Threads description: Threads group related trace invocations and their aggregate usage - name: Skills description: >- Skills are modular instructions you can use to codify processes and conventions - name: Smart Routers description: >- Create and manage workspace Smart Routers. A Smart Router selects a model from an eligible pool for each request according to a quality, balanced, or cost profile. - name: Webhooks description: >- Create and manage webhooks that deliver workspace events to external HTTPS endpoints. - name: Workspaces description: >- A workspace is the tenant. Create is called from a user session during onboarding; Get, List, and Update are the public management surface. - name: Workspace Security description: >- Workspace-level domain verification and IP allowlist controls. These operations are restricted to workspace administrators. - name: Workspace Settings description: >- Workspace-level settings managed with a workspace credential. A workspace is the tenant, so these settings are a singleton — there is nothing to create or delete, only read and update. - name: Responses - description: Run agents on a cron cadence. Minimum firing interval is 1 hour. name: Agent Schedules - name: Embeddings - name: Telemetry description: >- Unified query envelope for traces, metrics, and logs. One request shape, one filter dialect, and one response shape per source, validated by a per-source registry. - description: Beta. Run typed classification questions against a classify model. name: Classify - description: Search Gateway with managed credits or BYOK. name: Web Search externalDocs: url: https://docs.orq.ai description: orq.ai Documentation paths: /v2/tools/{tool_id}: get: tags: - Tools summary: Retrieve tool description: Retrieves a tool by id. operationId: RetrieveTool parameters: - schema: type: string required: true name: tool_id in: path responses: '200': description: Successfully retrieved the tool. content: application/json: schema: oneOf: - type: object properties: _id: type: string default: tool_01M2K22M91TQ8S6FD4X7T9X7GC path: type: string description: >- Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element must be the display name of an existing project, followed by nested folders (auto-created as needed). Example: `Default Project/agents`. With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: `agents`. For backward compatibility, a leading project name is ignored when it matches the scoped project. example: Default Project key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: >- Unique key of the tool as it will be displayed in the UI display_name: type: string description: >- The name of the tool as it will be displayed in the UI. This is optional and if not provided, the `key` will be used. description: type: string description: >- A description of the tool, used by the model to choose when and how to call the tool. We do recommend using the `description` field as accurate as possible to give enough context to the model to make the right decision. created_by_id: type: - string - 'null' description: The id of the user that created the tool updated_by_id: type: - string - 'null' description: The id of the user that last updated the tool project_id: type: string workspace_id: type: string created: type: string updated: type: string status: type: string enum: - live - draft - pending - published default: live description: >- The status of the tool. `Live` is the latest version of the tool. `Draft` is a version that is not yet published. `Pending` is a version that is pending approval. `Published` is a version that was live and has been replaced by a new version. type: type: string enum: - function function: type: object properties: name: type: string description: >- The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. description: type: string description: >- A description of what the function does, used by the model to choose when and how to call the function. strict: type: boolean description: >- Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Currently only compatible with `OpenAI` models. parameters: type: object properties: type: type: string enum: - object description: The type must be "object" properties: type: object additionalProperties: {} description: The properties of the function parameters required: type: array items: type: string description: Array of required parameter names required: - type - properties - required additionalProperties: {} description: >- The parameters the functions accepts, described as a JSON Schema object. See the `OpenAI` [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. required: - name required: - path - key - description - project_id - workspace_id - created - updated - type - function title: Function Tool description: >- A custom function tool that allows the model to call predefined functions with structured parameters. - type: object properties: _id: type: string default: tool_01M2K22M91E09SKB768NHHC608 path: type: string description: >- Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element must be the display name of an existing project, followed by nested folders (auto-created as needed). Example: `Default Project/agents`. With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: `agents`. For backward compatibility, a leading project name is ignored when it matches the scoped project. example: Default Project key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: >- Unique key of the tool as it will be displayed in the UI display_name: type: string description: >- The name of the tool as it will be displayed in the UI. This is optional and if not provided, the `key` will be used. description: type: string description: >- A description of the tool, used by the model to choose when and how to call the tool. We do recommend using the `description` field as accurate as possible to give enough context to the model to make the right decision. created_by_id: type: - string - 'null' description: The id of the user that created the tool updated_by_id: type: - string - 'null' description: The id of the user that last updated the tool project_id: type: string workspace_id: type: string created: type: string updated: type: string status: type: string enum: - live - draft - pending - published default: live description: >- The status of the tool. `Live` is the latest version of the tool. `Draft` is a version that is not yet published. `Pending` is a version that is pending approval. `Published` is a version that was live and has been replaced by a new version. type: type: string enum: - json_schema json_schema: type: object properties: name: type: string minLength: 1 maxLength: 64 description: >- The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. description: type: string description: >- A description of what the response format is for. This will be shown to the user. schema: type: object properties: type: type: string description: The JSON Schema type properties: type: object additionalProperties: {} description: The properties of the JSON Schema object required: type: array items: type: string description: Array of required property names required: - type - properties - required additionalProperties: {} description: >- The schema for the response format, described as a JSON Schema object. See the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. strict: type: boolean description: >- Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the `schema` field. Only a subset of JSON Schema is supported when `strict` is `true`. Only compatible with `OpenAI` models. required: - name - description - schema required: - path - key - description - project_id - workspace_id - created - updated - type - json_schema title: JSON Schema Tool description: >- A tool that enforces structured output format using JSON Schema for consistent response formatting. - type: object properties: _id: type: string default: tool_01M2K22M92EGDQZB200XTZ6WSY path: type: string description: >- Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element must be the display name of an existing project, followed by nested folders (auto-created as needed). Example: `Default Project/agents`. With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: `agents`. For backward compatibility, a leading project name is ignored when it matches the scoped project. example: Default Project key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: >- Unique key of the tool as it will be displayed in the UI display_name: type: string description: >- The name of the tool as it will be displayed in the UI. This is optional and if not provided, the `key` will be used. description: type: string description: >- A description of the tool, used by the model to choose when and how to call the tool. We do recommend using the `description` field as accurate as possible to give enough context to the model to make the right decision. created_by_id: type: - string - 'null' description: The id of the user that created the tool updated_by_id: type: - string - 'null' description: The id of the user that last updated the tool project_id: type: string workspace_id: type: string created: type: string updated: type: string status: type: string enum: - live - draft - pending - published default: live description: >- The status of the tool. `Live` is the latest version of the tool. `Draft` is a version that is not yet published. `Pending` is a version that is pending approval. `Published` is a version that was live and has been replaced by a new version. type: type: string enum: - http http: type: object properties: blueprint: type: object properties: url: type: string description: The URL to send the request to. method: type: string enum: - GET - POST - PUT - DELETE description: The HTTP method to use. headers: type: object additionalProperties: anyOf: - type: string - type: object properties: value: type: string encrypted: type: boolean default: false required: - value default: Content-Type: value: application/json encrypted: false description: >- The headers to send with the request. Can be a string value or an object with value and encrypted properties. body: type: object additionalProperties: {} description: The body to send with the request. timeout: type: number minimum: 1 maximum: 600 description: >- The request timeout in seconds. Defaults to 60 seconds when not set. When used in an agent, tool executions are also bound by the agent run `limits.tool_timeout` (default 5 minutes), so raise that limit for longer-running tools. required: - url - method description: >- The blueprint for the HTTP request. The `arguments` field will be used to replace the placeholders in the `url`, `headers`, `body`, and `arguments` fields. arguments: type: object additionalProperties: type: object properties: type: type: string enum: - string - number - boolean description: The type of the argument. description: type: string description: A description of the argument. send_to_model: type: boolean default: true description: >- Whether to send the argument to the model. If set to false, the argument will not be sent to the model and needs to be provided by the user or it will be left blank. default_value: anyOf: - type: string - type: number - type: boolean description: The default value of the argument. required: - type - description description: >- The arguments to send with the request. The keys will be used to replace the placeholders in the `blueprint` field. required: - blueprint required: - path - key - description - project_id - workspace_id - created - updated - type - http title: HTTP Tool description: >- Executes HTTP requests to interact with external APIs and web services using customizable blueprints. - type: object properties: _id: type: string default: tool_01M2K22M922KRVFZWEA25YEGN8 path: type: string description: >- Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element must be the display name of an existing project, followed by nested folders (auto-created as needed). Example: `Default Project/agents`. With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: `agents`. For backward compatibility, a leading project name is ignored when it matches the scoped project. example: Default Project key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: >- Unique key of the tool as it will be displayed in the UI display_name: type: string description: >- The name of the tool as it will be displayed in the UI. This is optional and if not provided, the `key` will be used. description: type: string description: >- A description of the tool, used by the model to choose when and how to call the tool. We do recommend using the `description` field as accurate as possible to give enough context to the model to make the right decision. created_by_id: type: - string - 'null' description: The id of the user that created the tool updated_by_id: type: - string - 'null' description: The id of the user that last updated the tool project_id: type: string workspace_id: type: string created: type: string updated: type: string status: type: string enum: - live - draft - pending - published default: live description: >- The status of the tool. `Live` is the latest version of the tool. `Draft` is a version that is not yet published. `Pending` is a version that is pending approval. `Published` is a version that was live and has been replaced by a new version. type: type: string enum: - code code_tool: type: object properties: parameters: type: object properties: type: type: string enum: - object description: The type must be "object" properties: type: object additionalProperties: {} description: The properties of the function parameters required: type: array items: type: string description: Array of required parameter names required: - type - properties - required additionalProperties: {} description: >- The parameters the functions accepts, described as a JSON Schema object. See the `OpenAI` [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. language: type: string enum: - python code: type: string minLength: 1 description: The code to execute. required: - language - code required: - path - key - description - project_id - workspace_id - created - updated - type - code_tool title: Code Execution Tool description: >- Executes code snippets in a sandboxed environment, currently supporting Python. components: securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.