search_tools
The primary discovery tool. Accepts a natural-language query and returns tool recommendations through ToolPilot’s multi-stage pipeline: BM25 + vector search → contextual filters → graph reranking → final selection.
When to use
Call search_tools whenever an agent needs to find the right developer tool for a task. The pipeline may return results immediately or ask clarification questions first — depending on how specific the query is and whether context filters are provided.
Input schema
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
query | string | Required | — | Natural language search query describing the tool you need. |
context | object | Optional | — | Optional pre-filters to skip clarification questions and jump directly to results. |
context.language | string | Optional | — | Programming language filter (e.g. "TypeScript", "Python", "Go"). |
context.category | string | Optional | — | Tool category filter (e.g. "database", "testing", "monitoring"). |
context.license | string | Optional | — | License type filter (e.g. "MIT", "Apache-2.0", "proprietary"). |
context.deployment | string | Optional | — | Deployment model filter (e.g. "self-hosted", "cloud", "serverless"). |
queryRequiredstringNatural language search query describing the tool you need.
contextOptionalobjectOptional pre-filters to skip clarification questions and jump directly to results.
context.languageOptionalstringProgramming language filter (e.g. "TypeScript", "Python", "Go").
context.categoryOptionalstringTool category filter (e.g. "database", "testing", "monitoring").
context.licenseOptionalstringLicense type filter (e.g. "MIT", "Apache-2.0", "proprietary").
context.deploymentOptionalstringDeployment model filter (e.g. "self-hosted", "cloud", "serverless").
Examples
Basic search
Search with context
Full context filters
{
"query": "monitoring and observability",
"context": {
"language": "Go",
"category": "monitoring",
"license": "Apache-2.0",
"deployment": "self-hosted"
}
}Skip clarification
context object lets the pipeline skip the clarification stage and return results directly. The more context you provide, the faster and more accurate the results.Response format
The response type field determines the shape of the payload. There are two possible response types:
Clarification needed
Returned when the query is ambiguous and the pipeline needs more information. Pass the query_id and your answers to search_tools_respond to complete the search.
{
"type": "clarification",
"query_id": "q_abc123def456",
"questions": [
{
"key": "language",
"question": "What programming language are you using?",
"options": ["Python", "TypeScript", "Go", "Java", "Rust"]
},
{
"key": "deployment",
"question": "What deployment model do you prefer?",
"options": ["cloud", "self-hosted", "serverless"]
}
]
}Results ready
Returned when the pipeline has enough information to produce results. Includes a primary recommendation and ranked alternatives.
{
"type": "result",
"recommendation": {
"name": "Prisma",
"description": "Next-generation TypeScript ORM for PostgreSQL, MySQL, and SQLite",
"category": "database",
"language": "TypeScript",
"license": "Apache-2.0",
"health_tier": "healthy",
"confidence": 0.94,
"reasons": [
"Strong TypeScript support with generated types",
"Native PostgreSQL support with migrations",
"Active community with 35k+ GitHub stars"
]
},
"alternatives": [
{
"name": "Drizzle ORM",
"confidence": 0.87,
"description": "Lightweight TypeScript ORM with SQL-like syntax"
},
{
"name": "TypeORM",
"confidence": 0.72,
"description": "Mature ORM for TypeScript and JavaScript"
}
]
}Error codes
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
400 | Bad Request | Optional | — | Invalid or empty query string. Ensure the query parameter is a non-empty string. |
500 | Internal Error | Optional | — | Pipeline processing error. An unexpected failure occurred in the search pipeline. Retry or contact support. |
400OptionalBad RequestInvalid or empty query string. Ensure the query parameter is a non-empty string.
500OptionalInternal ErrorPipeline processing error. An unexpected failure occurred in the search pipeline. Retry or contact support.
Related tools
search_tools_respond— Answer clarification questions to complete a searchget_stack— Build a compatible tool stack for a use casereport_outcome— Report usage feedback to improve future results