search_candidates
Find U.S. political candidates by name, state, office, or election year to access Federal Election Commission campaign finance data.
Instructions
Search for candidates by name or other criteria
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Candidate name search string | |
| state | No | Optional: Two-letter state code | |
| office | No | Optional: H for House, S for Senate, P for President | |
| election_year | No | Optional: Filter by election year |
Implementation Reference
- src/server.ts:512-540 (handler)The handler function that implements the search_candidates tool logic: validates arguments using Zod, queries the OpenFEC API endpoint /candidates/search, and returns the response as JSON text content.
private async handleSearchCandidates(args: any) { const schema = z.object({ name: z.string(), state: z.string().optional(), office: z.enum(['H', 'S', 'P']).optional(), election_year: z.number().optional(), }); const { name, state, office, election_year } = schema.parse(args); this.rateLimiter.consumeToken(); const response = await this.axiosInstance.get('/candidates/search', { params: { q: name, state, office, election_year, }, }); return { content: [ { type: 'text', text: JSON.stringify(response.data, null, 2), }, ], }; } - src/server.ts:132-154 (schema)Input schema definition for the search_candidates tool, defining parameters like name (required), state, office, and election_year.
inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Candidate name search string', }, state: { type: 'string', description: 'Optional: Two-letter state code', }, office: { type: 'string', description: 'Optional: H for House, S for Senate, P for President', enum: ['H', 'S', 'P'], }, election_year: { type: 'number', description: 'Optional: Filter by election year', }, }, required: ['name'], }, - src/server.ts:129-155 (registration)Registration of the search_candidates tool in the ListTools response, including name, description, and input schema.
{ name: 'search_candidates', description: 'Search for candidates by name or other criteria', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Candidate name search string', }, state: { type: 'string', description: 'Optional: Two-letter state code', }, office: { type: 'string', description: 'Optional: H for House, S for Senate, P for President', enum: ['H', 'S', 'P'], }, election_year: { type: 'number', description: 'Optional: Filter by election year', }, }, required: ['name'], }, }, - src/server.ts:449-450 (registration)Dispatch case in CallToolRequest handler that routes search_candidates calls to the handleSearchCandidates method.
case 'search_candidates': return await this.handleSearchCandidates(request.params.arguments); - src/server.ts:513-518 (schema)Zod runtime validation schema used inside the handler, matching the tool's inputSchema.
const schema = z.object({ name: z.string(), state: z.string().optional(), office: z.enum(['H', 'S', 'P']).optional(), election_year: z.number().optional(), });