search_by_tsn
Find organisms in the ITIS database using their Taxonomic Serial Number (TSN) to retrieve accurate taxonomic information.
Instructions
Search for organisms by their Taxonomic Serial Number (TSN) in ITIS database.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tsn | Yes | Taxonomic Serial Number (TSN) to search for |
Implementation Reference
- src/tools.ts:307-322 (handler)MCP tool handler for 'search_by_tsn': extracts TSN argument, calls itisClient.searchByTSN, and returns formatted JSON response with search results.
case 'search_by_tsn': { const { tsn } = args as any; const result = await itisClient.searchByTSN(tsn); return { content: [ { type: 'text', text: JSON.stringify({ tsn, totalResults: result.response.numFound, results: result.response.docs, }, null, 2), }, ], }; } - src/tools.ts:69-82 (schema)Tool schema definition: specifies name, description, and input schema requiring a 'tsn' string parameter.
{ name: 'search_by_tsn', description: 'Search for organisms by their Taxonomic Serial Number (TSN) in ITIS database.', inputSchema: { type: 'object', properties: { tsn: { type: 'string', description: 'Taxonomic Serial Number (TSN) to search for', }, }, required: ['tsn'], }, }, - src/itis-client.ts:160-165 (helper)Core helper function in ITISClient that performs SOLR search by TSN using the base search method with query 'tsn:${tsn}'.
async searchByTSN(tsn: string, options: Partial<ITISSearchOptions> = {}): Promise<ITISResponse> { return this.search({ ...options, query: `tsn:${tsn}`, }); } - src/tools.ts:11-257 (registration)The tools array exports all tool definitions including 'search_by_tsn', used for listing available tools via ListToolsRequestHandler.
export const tools: Tool[] = [ { name: 'search_itis', description: 'Search ITIS database using SOLR queries. Supports general search with flexible query parameters.', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'SOLR query string (e.g., "nameWInd:Homo*", "kingdom:Plantae", or "*:*" for all)', }, start: { type: 'number', description: 'Starting index for pagination (default: 0)', }, rows: { type: 'number', description: 'Number of results to return (default: 10, max: 100)', }, sort: { type: 'string', description: 'Sort order (e.g., "nameWInd asc", "tsn desc")', }, fields: { type: 'array', items: { type: 'string' }, description: 'Specific fields to return (default: all available fields)', }, filters: { type: 'object', additionalProperties: { type: 'string' }, description: 'Additional filters as key-value pairs (e.g., {"kingdom": "Animalia", "rank": "Species"})', }, }, }, }, { name: 'search_by_scientific_name', description: 'Search for organisms by their scientific name in ITIS database.', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Scientific name to search for (e.g., "Homo sapiens", "Quercus")', }, rows: { type: 'number', description: 'Number of results to return (default: 10)', }, start: { type: 'number', description: 'Starting index for pagination (default: 0)', }, }, required: ['name'], }, }, { name: 'search_by_tsn', description: 'Search for organisms by their Taxonomic Serial Number (TSN) in ITIS database.', inputSchema: { type: 'object', properties: { tsn: { type: 'string', description: 'Taxonomic Serial Number (TSN) to search for', }, }, required: ['tsn'], }, }, { name: 'search_by_kingdom', description: 'Search for organisms within a specific kingdom in ITIS database.', inputSchema: { type: 'object', properties: { kingdom: { type: 'string', description: 'Kingdom name (e.g., "Animalia", "Plantae", "Fungi", "Bacteria")', }, rows: { type: 'number', description: 'Number of results to return (default: 10)', }, start: { type: 'number', description: 'Starting index for pagination (default: 0)', }, }, required: ['kingdom'], }, }, { name: 'search_by_rank', description: 'Search for organisms by their taxonomic rank in ITIS database.', inputSchema: { type: 'object', properties: { rank: { type: 'string', description: 'Taxonomic rank (e.g., "Species", "Genus", "Family", "Order", "Class", "Phylum", "Kingdom")', }, rows: { type: 'number', description: 'Number of results to return (default: 10)', }, start: { type: 'number', description: 'Starting index for pagination (default: 0)', }, }, required: ['rank'], }, }, { name: 'get_hierarchy', description: 'Get the complete taxonomic hierarchy for a given TSN.', inputSchema: { type: 'object', properties: { tsn: { type: 'string', description: 'Taxonomic Serial Number (TSN) to get hierarchy for', }, }, required: ['tsn'], }, }, { name: 'autocomplete_search', description: 'Search for organisms with autocomplete functionality using partial names.', inputSchema: { type: 'object', properties: { partialName: { type: 'string', description: 'Partial scientific name for autocomplete (e.g., "Homo", "Quer")', }, rows: { type: 'number', description: 'Number of results to return (default: 10)', }, }, required: ['partialName'], }, }, { name: 'get_statistics', description: 'Get basic statistics about the ITIS database (total number of records).', inputSchema: { type: 'object', properties: {}, }, }, { name: 'search_by_vernacular_name', description: 'Search for organisms by their common/vernacular names in ITIS database.', inputSchema: { type: 'object', properties: { vernacularName: { type: 'string', description: 'Common/vernacular name to search for (e.g., "human", "dog", "oak tree")', }, rows: { type: 'number', description: 'Number of results to return (default: 10)', }, start: { type: 'number', description: 'Starting index for pagination (default: 0)', }, }, required: ['vernacularName'], }, }, { name: 'explore_taxonomy', description: 'Explore taxonomic relationships by finding related organisms at different taxonomic levels.', inputSchema: { type: 'object', properties: { scientificName: { type: 'string', description: 'Scientific name to explore (e.g., "Homo sapiens")', }, level: { type: 'string', description: 'Taxonomic level to explore: "siblings" (same genus), "family" (same family), "order" (same order), "class" (same class)', enum: ['siblings', 'family', 'order', 'class'] }, rows: { type: 'number', description: 'Number of results to return (default: 10)', }, }, required: ['scientificName', 'level'], }, }, { name: 'get_random_species', description: 'Get random species from ITIS database with optional taxonomic filters.', inputSchema: { type: 'object', properties: { kingdom: { type: 'string', description: 'Kingdom filter (e.g., "Animalia", "Plantae", "Fungi")', }, phylum: { type: 'string', description: 'Phylum filter (e.g., "Chordata", "Arthropoda")', }, class: { type: 'string', description: 'Class filter (e.g., "Mammalia", "Aves", "Reptilia")', }, order: { type: 'string', description: 'Order filter (e.g., "Carnivora", "Primates")', }, family: { type: 'string', description: 'Family filter (e.g., "Felidae", "Canidae")', }, genus: { type: 'string', description: 'Genus filter (e.g., "Panthera", "Canis")', }, count: { type: 'number', description: 'Number of random species to return (default: 1, max: 10)', }, requireVernacular: { type: 'boolean', description: 'Only return species that have common names (default: false)', }, vernacularLanguage: { type: 'string', description: 'Language for vernacular names (default: "English"). Other options: "French", "Spanish", etc.', }, }, }, }, ];