build_scryfall_query
Transform natural language into optimized Scryfall search queries for Magic: The Gathering cards. Specify formats, budget, and optimization strategies to get precise or broad results with explanations and alternatives.
Instructions
Convert natural language requests into optimized Scryfall search queries with explanations and alternatives
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| explain_mapping | No | Whether to include detailed explanation of natural language to Scryfall mapping | |
| format | No | Magic format to restrict search to (optional) | |
| include_alternatives | No | Whether to include alternative query suggestions | |
| max_results | No | Target number of results for optimization | |
| natural_query | Yes | Natural language description of what you want to find (e.g., "red creatures under $5 for aggressive decks", "blue counterspells in modern") | |
| optimize_for | No | Search optimization strategy: precision (fewer, more relevant results), recall (broader search), discovery (interesting cards), budget (cost-effective) | precision |
| price_budget | No | Price constraints for the search | |
| test_query | No | Whether to test the generated query and optimize based on results |
Implementation Reference
- The main execute method implementing the tool logic: validates input, parses natural language, builds and tests Scryfall query, formats response.async execute(args: unknown) { try { // Validate input parameters const params = validateBuildQueryParams(args); // Sanitize natural language input (using a more permissive approach for natural language) const sanitizedQuery = params.natural_query.trim() // eslint-disable-next-line no-control-regex .replace(/[\x00-\x1F\x7F-\x9F]/g, '') // Remove control characters .substring(0, 500); // Enforce max length if (!sanitizedQuery) { throw new ValidationError('Natural query cannot be empty after sanitization'); } // Parse natural language const parsed = this.parser.parse(sanitizedQuery, { targetFormat: params.format, optimizationStrategy: params.optimize_for, maxResults: params.max_results }); // Check parsing confidence if (parsed.confidence < 0.3) { return this.handleLowConfidenceParsing(parsed, params); } // Build Scryfall query const buildOptions = { optimize_for: params.optimize_for, format: params.format, max_results: params.max_results, price_budget: params.price_budget }; const buildResult = await this.queryBuilder.build(parsed, buildOptions); // Test query if requested (sanitize the generated query before testing) let testResult; if (params.test_query) { const sanitizedTestQuery = sanitizeQuery(buildResult.query); testResult = await this.testQuery(sanitizedTestQuery); } // Format response const responseText = this.formatResponse( buildResult, testResult, params, parsed ); return { content: [{ type: 'text', text: responseText }] }; } catch (error) { return this.handleError(error); } }
- Input schema defining parameters for the build_scryfall_query tool, including natural_query, format, optimization options, etc.readonly inputSchema = { type: 'object' as const, properties: { natural_query: { type: 'string', description: 'Natural language description of what you want to find (e.g., "red creatures under $5 for aggressive decks", "blue counterspells in modern")', minLength: 1, maxLength: 500 }, format: { type: 'string', enum: ['standard', 'modern', 'legacy', 'vintage', 'commander', 'pioneer', 'brawl', 'pauper', 'penny', 'historic', 'alchemy'], description: 'Magic format to restrict search to (optional)' }, optimize_for: { type: 'string', enum: ['precision', 'recall', 'discovery', 'budget'], default: 'precision', description: 'Search optimization strategy: precision (fewer, more relevant results), recall (broader search), discovery (interesting cards), budget (cost-effective)' }, max_results: { type: 'number', minimum: 1, maximum: 175, default: 20, description: 'Target number of results for optimization' }, price_budget: { type: 'object', properties: { max: { type: 'number', minimum: 0, description: 'Maximum price per card' }, currency: { type: 'string', enum: ['usd', 'eur', 'tix'], default: 'usd', description: 'Currency for price constraints' } }, description: 'Price constraints for the search' }, include_alternatives: { type: 'boolean', default: true, description: 'Whether to include alternative query suggestions' }, explain_mapping: { type: 'boolean', default: true, description: 'Whether to include detailed explanation of natural language to Scryfall mapping' }, test_query: { type: 'boolean', default: true, description: 'Whether to test the generated query and optimize based on results' } }, required: ['natural_query'] };
- src/server.ts:77-77 (registration)Registration of the BuildScryfallQueryTool instance in the server's tools map under the name 'build_scryfall_query'.this.tools.set("build_scryfall_query", new BuildScryfallQueryTool(this.scryfallClient));
- src/tools/build-scryfall-query.ts:27-28 (handler)Class definition with tool name and description.export class BuildScryfallQueryTool { readonly name = 'build_scryfall_query';