kegg-mcp-server

search_pathways

Read-onlyIdempotent

Search KEGG pathways by keyword and optional organism code to locate relevant pathway records for analysis.

Instructions

Search KEGG pathways by keyword.

Args: query: Search term (e.g. 'glycolysis', 'TCA', 'insulin signaling'). organism_code: 3-4 letter organism code (e.g. 'hsa' for human, 'mmu' for mouse). Use 'map' for reference pathways. max_results: Maximum number of results to return (capped at 100).

Input Schema

Name	Required	Default
`query`	Yes
`max_results`	No
`organism_code`	No	map

Output Schema

Name	Required	Description	Default
`query`	Yes
`results`	Yes
`database`	Yes
`truncated`	No
`total_found`	Yes
`returned_count`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedv0.5.0Oct 23, 2026

removedOutput schema / $defs

Removed value: -{
-  "ErrorResult": {
-    "description": "Structured error returned by a tool when the KEGG API fails.\n\nA tool returns this instead of raising so the model can reason about\nthe failure and decide whether to retry, change inputs, or give up.\nA point lookup that receives a 404 uses code ``not_found``; an empty search\nremains a successful result with no items.",
-    "properties": {
-      "code": {
-        "default": "kegg_api_error",
-        "title": "Code",
-        "type": "string"
-      },
-      "error": {
-        "title": "Error",
-        "type": "string"
-      },
-      "hint": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "title": "Hint"
-      },
-      "path": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "title": "Path"
-      },
-      "retryable": {
-        "default": false,
-        "title": "Retryable",
-        "type": "boolean"
-      },
-      "status": {
-        "anyOf": [
-          {
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "title": "Status"
-      }
-    },
-    "required": [
-      "error"
-    ],
-    "title": "ErrorResult",
-    "type": "object"
-  },
-  "SearchResult": {
-    "properties": {
-      "database": {
-        "title": "Database",
-        "type": "string"
-      },
-      "query": {
-        "title": "Query",
-        "type": "string"
-      },
-      "results": {
-        "additionalProperties": {
-          "type": "string"
-        },
-        "title": "Results",
-        "type": "object"
-      },
-      "returned_count": {
-        "title": "Returned Count",
-        "type": "integer"
-      },
-      "total_found": {
-        "title": "Total Found",
-        "type": "integer"
-      },
-      "truncated": {
-        "default": false,
-        "title": "Truncated",
-        "type": "boolean"
-      }
-    },
-    "required": [
-      "query",
-      "database",
-      "total_found",
-      "returned_count",
-      "results"
-    ],
-    "title": "SearchResult",
-    "type": "object"
-  }
-}

addedOutput schema / properties / database

Added value: +{
+  "title": "Database",
+  "type": "string"
+}

addedOutput schema / properties / query

Added value: +{
+  "title": "Query",
+  "type": "string"
+}

removedOutput schema / properties / result

Removed value: -{
-  "anyOf": [
-    {
-      "$ref": "#/$defs/SearchResult"
-    },
-    {
-      "$ref": "#/$defs/ErrorResult"
-    }
-  ],
-  "title": "Result"
-}

addedOutput schema / properties / results

Added value: +{
+  "additionalProperties": {
+    "type": "string"
+  },
+  "title": "Results",
+  "type": "object"
+}

addedOutput schema / properties / returned_count

Added value: +{
+  "title": "Returned Count",
+  "type": "integer"
+}

addedOutput schema / properties / total_found

Added value: +{
+  "title": "Total Found",
+  "type": "integer"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "default": false,
+  "title": "Truncated",
+  "type": "boolean"
+}

changedOutput schema / required

Previous value: -[
-  "result"
-]New value: +[
+  "query",
+  "database",
+  "total_found",
+  "returned_count",
+  "results"
+]

changedOutput schema / title

Previous value: -"search_pathwaysOutput"New value: +"SearchResult"

First observedv0.1.0Jul 29, 2026

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds two pieces of real behavioral context the annotations lack: results are capped at 100 regardless of max_results, and organism_code='map' yields reference rather than organism-specific pathways. It doesn't disclose matching field or case/paging behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded purpose sentence followed by an Args block; no filler. Because structured coverage is 0%, restating the parameters with added semantics is justified rather than redundant, though the block could fold into prose more tightly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and all three parameters are addressed. Remaining gaps are minor: keyword matching scope, default values (25, map), and what to do if results exceed the 100 cap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry all param meaning, and it largely does: example query terms, the 3-4 letter organism code format with 'hsa'/'mmu' examples and the 'map' special value, and the 100-result ceiling on max_results. It omits the default values and doesn't say which fields the keyword is matched against.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('search') and resource ('KEGG pathways') with the matching mode ('by keyword'), which cleanly separates it from search_reactions, search_compounds and search_brite. It never names a sibling or says explicitly that get_pathway_info is the follow-up for a hit, so it stops short of full differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer this is the entry point before calling get_pathway_info / get_pathway_genes, but nothing states when to prefer it or when not. The 'map' note gives a hint about reference pathways, but no explicit selection criteria between tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.