chembl-mcp-server

chembl-get-bioactivities

chembl_get_bioactivities

Read-onlyIdempotent

The flagship compound↔target bioactivity bridge: measurements for a molecule (target deconvolution / selectivity), a target (lead finding), or both together (how potently one compound hits one target). Supply at least one of molecule_chembl_id (from chembl_search_molecules) or target_chembl_id (from chembl_search_targets) — supplying both narrows to that compound–target pair, supplying neither is an error. A drug's measurements are often split across its salts and other alternate forms, so molecule_chembl_id reads that one form unless include_alternate_forms widens it to the whole family under its parent (a salt's ID included), every view, page, and spill reading the same family. Filter by standard_type (IC50/Ki/EC50/…), minimum potency pchembl_value_min, assay_type, organism, and variant (wild type, or one recorded mutant such as "T315I"). Each row carries its activity_comment and data_validity_comment, its assay variant, and its source document for citation. Not every measurement has a derivable pchembl_value, so potency_view picks which side of that split you get: the default "potency_ranked" returns the measurements that have one, most potent first (ChEMBL sorts the rest first otherwise, which is why they are not merged), and "null_potency" returns exactly the measurements that have none. totalCount is the honest full match count across both views either way. Mixing measurement types (IC50 vs Ki) is a scientific error — set standard_type to compare like with like. A popular target carries tens of thousands of rows: results spill to a DataCanvas table (call chembl_dataframe_describe for its columns, then chembl_dataframe_query for honest aggregates across the staged set), while an inline preview answers the immediate question. Each view stages its own table (bioactivities / bioactivities_null_potency), so running both against one canvas_id lets a UNION ALL rebuild the full set. A canvas is minted only when a view spills; pass its canvas_id back and every later non-cursor call re-stages the table of its view with its own rows, even when they fit inline or none match, so a successful call never leaves rows from an earlier query in it, and a spill that fails or is cancelled leaves the earlier table in place. The spill is bounded by a row cap (CHEMBL_MAX_SPILL_ROWS) and a time budget (CHEMBL_SPILL_DEADLINE_MS); when either stops it short of the view, truncated is true, truncated_by names the bound, and the table is a bounded slice, not the complete view. The inline rows are always capped at limit, so compare that against totalCount before treating them as the whole answer. Spilling needs the canvas, which is on unless the server sets CANVAS_PROVIDER_TYPE=none. Whenever a call stages nothing and rows remain past this page — the canvas is off, or the view fit inline with no canvas_id — nextCursor continues the view: pass it back as cursor, with the same filters and potency_view, for the next page. A cursor page is always returned inline and never staged, canvas or not.

Input Schema

Name	Required	Description	Default
`limit`	No	Maximum rows in the inline preview or cursor page, up to 1000 — a larger value is served at 1000, with a notice saying so. Defaults to the server default (25). With the canvas enabled, a view that spills still stages in full whatever the limit; when a call stages nothing, nextCursor reaches the rows past limit.
`cursor`	No	Opaque continuation token from a previous call's nextCursor — resumes the view where that page ended. Omit for the first page. Re-send the same molecule_chembl_id/target_chembl_id, include_alternate_forms, filters, and potency_view that minted it (only limit may change; it sets this page's size); redeeming it against different filters walks a different result set. A cursor page is returned inline and never staged, even with the canvas enabled.
`variant`	No	Restrict to one assay variant of the target. "wild_type" keeps the measurements that record no variant. Any other value keeps those whose recorded assay_variant_mutation equals it whole, case-insensitively, with spaces beside "," or "/" ignored: a substitution ("T315I"), a deletion ("F508del"), a multi-mutant in the order ChEMBL records it ("L858R,T790M"; "T790M,L858R" matches nothing, and "L858R" alone matches only the single mutant), or "UNDEFINED MUTATION" for an unspecified mutant. Read assay_variant_mutation on unfiltered rows for the recorded strings.
`organism`	No	Restrict to a target organism, e.g. "Homo sapiens" (case-insensitive exact match).
`canvas_id`	No	Optional canvas ID from a prior call to reuse the same canvas. With it, the call re-stages the selected potency_view's table with this call's rows whether they spill, fit inline, or are empty, so a second query of the SAME view REPLACES (overwrites) its prior rows once it succeeds — it does not append, and a spill that fails or is cancelled leaves them — while the other view's table is left intact, which is what lets both coexist on one canvas. Omit it and a fresh canvas is minted only if the view spills. Left untouched on a cursor page, which never stages.
`assay_type`	No	Restrict to an assay type code: "B" (binding), "F" (functional), "A" (ADMET), "T" (toxicity), "P" (physicochemical), "U" (unassigned).
`potency_view`	No	Which side of the pchembl_value presence split to retrieve. "potency_ranked" (default) returns the measurements that have a derivable pchembl_value, most potent first. "null_potency" returns exactly the measurements that have none — the rows the ranked view excludes, otherwise unreachable. The two partition the match set and stage to separate canvas tables.	potency_ranked
`standard_type`	No	Restrict to one measurement type, e.g. "IC50", "Ki", "EC50". Matched exactly, case included — ChEMBL records distinct types that differ only by case, such as "Kd" and "KD". Set this to compare potencies validly.
`target_chembl_id`	No	ChEMBL target ID (from chembl_search_targets), e.g. "CHEMBL203". Supply this, molecule_chembl_id, or both — both narrows to that compound–target pair.
`pchembl_value_min`	No	Minimum pchembl_value (−log10 molar potency), e.g. 7 keeps sub-100 nM activities. Only valid on the potency_ranked view — the null_potency rows have no pchembl_value to compare against.
`molecule_chembl_id`	No	ChEMBL molecule ID (from chembl_search_molecules), e.g. "CHEMBL941". Supply this, target_chembl_id, or both — both narrows to that compound–target pair.
`include_alternate_forms`	No	Widen molecule_chembl_id to its whole family: the parent it belongs to and every salt and other alternate form ChEMBL files under it (a drug's measurements are often split across them). A salt's ID reaches its parent's family; each row keeps the molecule_chembl_id of the form it was measured on. Requires molecule_chembl_id; combines with target_chembl_id and every filter. Defaults to false: that one form's measurements only.

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance when no measurements matched (naming the spelling ChEMBL records when the standard_type sent differs from it only by case), how to SQL the staged set, or which rows of the view an inline page holds and how to continue it — led by the disclosure that a limit above the maximum was served at the maximum.
`spilled`	No	True when the view exceeded the inline preview and spilled to the canvas. False when it fit inline — including an inline fit re-staged on a supplied canvas_id, which table_name and staged_row_count report.
`canvas_id`	No	Canvas ID holding the staged table — pass to chembl_dataframe_describe to list its columns, then to chembl_dataframe_query to run SQL over them. Null when nothing was staged: canvas disabled, a cursor page, or an inline fit with no canvas_id supplied.
`truncated`	No	True when a bound stopped the page walk short of the view — the CHEMBL_MAX_SPILL_ROWS row cap or the CHEMBL_SPILL_DEADLINE_MS time budget, as truncated_by says. The staged table is then a bounded slice, NOT the complete view, so aggregates over it are a sample. Narrow the filters to bring the view under the bound.
`activities`	No	Bioactivity rows for the selected potency_view — the inline preview, the cursor page, or the full view when it fit without spilling.
`nextCursor`	No	Opaque token for the next page of this view — pass it back as cursor with the same filters and potency_view. Minted only when nothing was staged and rows remain past this page: with the canvas disabled, on a cursor page, or when the view fit inline with no canvas_id supplied. Absent on the last page and whenever the call staged a table (a spill, or an inline fit re-staged on a supplied canvas_id).
`table_name`	No	Canvas table name holding the staged rowset, and the FROM target for chembl_dataframe_query SQL — "bioactivities" for potency_ranked, "bioactivities_null_potency" for null_potency. Null when nothing was staged.
`totalCount`	No	Total matching measurements upstream — the honest full count spanning BOTH potency views, before any preview cap. The staged/preview rows are the selected view of this.
`potency_view`	No	Which view these rows came from: "potency_ranked" = measurements with a derivable pchembl_value; "null_potency" = measurements with none. Re-call with the other value to reach the rest of totalCount.
`truncated_by`	No	The bound that cut the staged table short when truncated is true: "row_cap" — the CHEMBL_MAX_SPILL_ROWS cap; "time_budget" — the CHEMBL_SPILL_DEADLINE_MS budget ended the page walk, at its expiry or once what was left would not hold another page, so a re-call can stage more. Null when truncated is false.
`appliedFilters`	No	Filters as the server parsed them.
`canvasDisabled`	No	True when the server runs with the canvas off (CANVAS_PROVIDER_TYPE=none), so large sets could not spill — the inline rows are one page of the view, not the full set, and nextCursor continues it.
`staged_row_count`	No	Rows actually registered on the canvas table — 0 when a re-staged view matched nothing. Null when nothing was staged. Below the view total when truncated is true.

Schema Changelog

Changes observed during successful MCP inspections.

Changed23 schema fields changedOct 24, 2026

changedInput schema / properties / assay_type / description

Previous value: -"Restrict to an assay type code: \"B\" (binding), \"F\" (functional), \"A\" (ADMET), \"T\" (toxicity)."New value: +"Restrict to an assay type code: \"B\" (binding), \"F\" (functional), \"A\" (ADMET), \"T\" (toxicity), \"P\" (physicochemical), \"U\" (unassigned)."

addedInput schema / properties / assay_type / pattern

Added value: +"^\\s*(?:(?:[Bb]|[Bb][Ii][Nn][Dd][Ii][Nn][Gg]|[Ff]|[Ff][Uu][Nn][Cc][Tt][Ii][Oo][Nn][Aa][Ll]|[Aa]|[Aa][Dd][Mm][Ee]|[Aa][Dd][Mm][Ee][Tt]|[Tt]|[Tt][Oo][Xx][Ii][Cc][Ii][Tt][Yy]|[Pp]|[Pp][Hh][Yy][Ss][Ii][Cc][Oo][Cc][Hh][Ee][Mm][Ii][Cc][Aa][Ll]|[Uu]|[Uu][Nn][Aa][Ss][Ss][Ii][Gg][Nn][Ee][Dd]|[Uu][Nn][Cc][Ll][Aa][Ss][Ss][Ii][Ff][Ii][Ee][Dd])\\s*)?$"

changedInput schema / properties / cursor / description

Previous value: -"Opaque continuation token from a previous call's nextCursor — resumes the view where that page ended. Omit for the first page. Re-send the same molecule_chembl_id/target_chembl_id, filters, and potency_view that minted it (only limit may change; it sets this page's size); redeeming it against different filters walks a different result set. A cursor page is returned inline and never staged, even with the canvas enabled."New value: +"Opaque continuation token from a previous call's nextCursor — resumes the view where that page ended. Omit for the first page. Re-send the same molecule_chembl_id/target_chembl_id, include_alternate_forms, filters, and potency_view that minted it (only limit may change; it sets this page's size); redeeming it against different filters walks a different result set. A cursor page is returned inline and never staged, even with the canvas enabled."

addedInput schema / properties / include_alternate_forms

Added value: +{
+  "default": false,
+  "description": "Widen molecule_chembl_id to its whole family: the parent it belongs to and every salt and other alternate form ChEMBL files under it (a drug's measurements are often split across them). A salt's ID reaches its parent's family; each row keeps the molecule_chembl_id of the form it was measured on. Requires molecule_chembl_id; combines with target_chembl_id and every filter. Defaults to false: that one form's measurements only.",
+  "type": "boolean"
+}

changedInput schema / properties / limit / description

Previous value: -"Maximum rows in the inline preview or cursor page. Defaults to the server default (25). With the canvas enabled, a call without cursor still spills the full set to the canvas; when a call stages nothing, nextCursor reaches the rows past limit."New value: +"Maximum rows in the inline preview or cursor page, up to 1000 — a larger value is served at 1000, with a notice saying so. Defaults to the server default (25). With the canvas enabled, a view that spills still stages in full whatever the limit; when a call stages nothing, nextCursor reaches the rows past limit."

changedInput schema / properties / limit / maximum
```
Previous value: -1000New value: +10000
```

changedInput schema / properties / standard_type / description

Previous value: -"Restrict to one measurement type, e.g. \"IC50\", \"Ki\", \"EC50\". Set this to compare potencies validly."New value: +"Restrict to one measurement type, e.g. \"IC50\", \"Ki\", \"EC50\". Matched exactly, case included — ChEMBL records distinct types that differ only by case, such as \"Kd\" and \"KD\". Set this to compare potencies validly."

addedInput schema / properties / target_chembl_id / pattern

Added value: +"^\\s*(?:[Cc][Hh][Ee][Mm][Bb][Ll]\\d+\\s*)?$"

addedInput schema / properties / variant

Added value: +{
+  "description": "Restrict to one assay variant of the target. \"wild_type\" keeps the measurements that record no variant. Any other value keeps those whose recorded assay_variant_mutation equals it whole, case-insensitively, with spaces beside \",\" or \"/\" ignored: a substitution (\"T315I\"), a deletion (\"F508del\"), a multi-mutant in the order ChEMBL records it (\"L858R,T790M\"; \"T790M,L858R\" matches nothing, and \"L858R\" alone matches only the single mutant), or \"UNDEFINED MUTATION\" for an unspecified mutant. Read assay_variant_mutation on unfiltered rows for the recorded strings.",
+  "type": "string"
+}

addedOutput schema / properties / activities / items / properties / activity_comment

Added value: +{
+  "description": "Depositor or curator comment on the result, free text such as \"Not Active\", \"Active\", or \"Inconclusive\" — often the only result when standard_value is null. Null when absent.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / activities / items / properties / assay_variant_accession

Added value: +{
+  "description": "UniProt accession of the variant protein, which can differ from the target's own. Null when no variant is recorded, and for UNDEFINED MUTATION.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / activities / items / properties / assay_variant_mutation

Added value: +{
+  "description": "Variant of the target protein the assay measured, as ChEMBL records it: a substitution (\"T315I\"), a deletion (\"F508del\"), several joined by \",\" or \"/\" (\"L858R,T790M\"), or \"UNDEFINED MUTATION\" for an unspecified mutant. Null when no variant is recorded.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / activities / items / properties / data_validity_comment

Added value: +{
+  "description": "ChEMBL data-validity annotation, e.g. \"Outside typical range\", \"Potential transcription error\", \"Non standard unit for type\", or \"Manually validated\" (a value curators confirmed). Null when unannotated.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / activities / items / properties / document_chembl_id

Added value: +{
+  "description": "ChEMBL document ID of the publication or deposited dataset the measurement comes from — cite it. Null when absent.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / activities / items / properties / document_year

Added value: +{
+  "description": "Publication year of the source document. Null when it has none, as for deposited datasets.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

changedOutput schema / properties / activities / items / required

Previous value: -[
-  "activity_id",
-  "molecule_chembl_id",
-  "molecule_pref_name",
-  "target_chembl_id",
-  "target_pref_name",
-  "target_organism",
-  "assay_chembl_id",
-  "assay_type",
-  "assay_description",
-  "standard_type",
-  "standard_relation",
-  "standard_value",
-  "standard_units",
-  "pchembl_value",
-  "type",
-  "value",
-  "units",
-  "relation"
-]New value: +[
+  "activity_id",
+  "molecule_chembl_id",
+  "molecule_pref_name",
+  "target_chembl_id",
+  "target_pref_name",
+  "target_organism",
+  "assay_chembl_id",
+  "assay_type",
+  "assay_description",
+  "standard_type",
+  "standard_relation",
+  "standard_value",
+  "standard_units",
+  "pchembl_value",
+  "type",
+  "value",
+  "units",
+  "relation",
+  "activity_comment",
+  "data_validity_comment",
+  "assay_variant_mutation",
+  "assay_variant_accession",
+  "document_chembl_id",
+  "document_year"
+]

changedOutput schema / properties / appliedFilters / properties / scope / description

Previous value: -"Which IDs scoped the query: the molecule, the target, or both when it narrowed to a compound–target pair."New value: +"Which IDs scoped the query: the molecule, the target, or both when it narrowed to a compound–target pair. Under include_alternate_forms the molecule side names the family parent whose forms were read."

addedOutput schema / properties / appliedFilters / properties / variant

Added value: +{
+  "description": "The variant filter applied — \"wild_type\", or the variant string matched, spaces beside separators removed — or null.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

changedOutput schema / properties / appliedFilters / required

Previous value: -[
-  "scope",
-  "standard_type",
-  "pchembl_value_min",
-  "assay_type",
-  "organism"
-]New value: +[
+  "scope",
+  "standard_type",
+  "pchembl_value_min",
+  "assay_type",
+  "organism",
+  "variant"
+]

changedOutput schema / properties / canvasDisabled / description

Previous value: -"True when CANVAS_PROVIDER_TYPE is not duckdb, so large sets could not spill — the inline rows are a capped preview, not the full set."New value: +"True when the server runs with the canvas off (CANVAS_PROVIDER_TYPE=none), so large sets could not spill — the inline rows are one page of the view, not the full set, and nextCursor continues it."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `not_found`: ChEMBL has no record for the requested identifier or structure. `rate_limited`: ChEMBL rate-limits the upstream request. `missing_filter`: Neither molecule_chembl_id nor target_chembl_id was supplied, so the query had nothing to scope to. `contradictory_potency_filter`: pchembl_value_min was supplied alongside potency_view \"null_potency\", whose rows have no pchembl_value for the floor to compare against — the combination can only ever match zero measurements. `canvas_capacity_exhausted`: The view spilled with no canvas_id supplied, and the tenant already holds as many canvases as CANVAS_MAX_CANVASES_PER_TENANT allows, so none could be minted to stage it. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `not_found`: ChEMBL has no record for the requested identifier or structure. `rate_limited`: ChEMBL rate-limits the upstream request. `missing_filter`: Neither molecule_chembl_id nor target_chembl_id was supplied, so the query had nothing to scope to. `not_a_chembl_id`: molecule_chembl_id is not a ChEMBL ID like CHEMBL941, so it could match no measurement. `alternate_forms_without_molecule`: include_alternate_forms was set without molecule_chembl_id, so there was no molecule whose family to read. `contradictory_potency_filter`: pchembl_value_min was supplied alongside potency_view \"null_potency\", whose rows have no pchembl_value for the floor to compare against — the combination can only ever match zero measurements. `canvas_capacity_exhausted`: The view spilled with no canvas_id supplied, and the tenant already holds as many canvases as CANVAS_MAX_CANVASES_PER_TENANT allows, so none could be minted to stage it. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "not_found",
-  "rate_limited",
-  "missing_filter",
-  "contradictory_potency_filter",
-  "canvas_capacity_exhausted"
-]New value: +[
+  "not_found",
+  "rate_limited",
+  "missing_filter",
+  "not_a_chembl_id",
+  "alternate_forms_without_molecule",
+  "contradictory_potency_filter",
+  "canvas_capacity_exhausted"
+]

changedOutput schema / properties / notice / description

Previous value: -"Guidance when no measurements matched, how to SQL the staged set, or which rows of the view an inline page holds and how to continue it."New value: +"Guidance when no measurements matched (naming the spelling ChEMBL records when the standard_type sent differs from it only by case), how to SQL the staged set, or which rows of the view an inline page holds and how to continue it — led by the disclosure that a limit above the maximum was served at the maximum."

Changed15 schema fields changedOct 18, 2026

changedInput schema / properties / canvas_id / description

Previous value: -"Optional canvas ID from a prior call to reuse the same canvas. Each potency_view re-stages its own table, so a second query of the SAME view REPLACES (overwrites) its prior rows — it does not append — while the other view's table is left intact, which is what lets both coexist on one canvas. Omit to mint a fresh canvas."New value: +"Optional canvas ID from a prior call to reuse the same canvas. With it, the call re-stages the selected potency_view's table with this call's rows whether they spill, fit inline, or are empty, so a second query of the SAME view REPLACES (overwrites) its prior rows once it succeeds — it does not append, and a spill that fails or is cancelled leaves them — while the other view's table is left intact, which is what lets both coexist on one canvas. Omit it and a fresh canvas is minted only if the view spills. Left untouched on a cursor page, which never stages."

addedInput schema / properties / cursor

Added value: +{
+  "description": "Opaque continuation token from a previous call's nextCursor — resumes the view where that page ended. Omit for the first page. Re-send the same molecule_chembl_id/target_chembl_id, filters, and potency_view that minted it (only limit may change; it sets this page's size); redeeming it against different filters walks a different result set. A cursor page is returned inline and never staged, even with the canvas enabled.",
+  "type": "string"
+}

changedInput schema / properties / limit / description

Previous value: -"Maximum rows in the inline preview. Defaults to the server default (25). The full set still spills to the canvas."New value: +"Maximum rows in the inline preview or cursor page. Defaults to the server default (25). With the canvas enabled, a call without cursor still spills the full set to the canvas; when a call stages nothing, nextCursor reaches the rows past limit."

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "activities",
-      "totalCount",
-      "potency_view",
-      "spilled",
-      "canvas_id",
-      "table_name",
-      "staged_row_count",
-      "truncated",
-      "canvasDisabled",
-      "appliedFilters"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "activities",
+      "totalCount",
+      "potency_view",
+      "spilled",
+      "canvas_id",
+      "table_name",
+      "staged_row_count",
+      "truncated",
+      "truncated_by",
+      "canvasDisabled",
+      "appliedFilters"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

changedOutput schema / properties / activities / description

Previous value: -"Bioactivity rows for the selected potency_view — the inline preview, or the full view when it fit without spilling."New value: +"Bioactivity rows for the selected potency_view — the inline preview, the cursor page, or the full view when it fit without spilling."

changedOutput schema / properties / canvas_id / description

Previous value: -"Canvas ID holding the staged table — pass to chembl_dataframe_describe to list its columns, then to chembl_dataframe_query to run SQL over them. Null when canvas is disabled or nothing spilled."New value: +"Canvas ID holding the staged table — pass to chembl_dataframe_describe to list its columns, then to chembl_dataframe_query to run SQL over them. Null when nothing was staged: canvas disabled, a cursor page, or an inline fit with no canvas_id supplied."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `not_found`: ChEMBL has no record for the requested identifier or structure. `rate_limited`: ChEMBL rate-limits the upstream request. `missing_filter`: Neither molecule_chembl_id nor target_chembl_id was supplied, so the query had nothing to scope to. `contradictory_potency_filter`: pchembl_value_min was supplied alongside potency_view \"null_potency\", whose rows have no pchembl_value for the floor to compare against — the combination can only ever match zero measurements. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `not_found`: ChEMBL has no record for the requested identifier or structure. `rate_limited`: ChEMBL rate-limits the upstream request. `missing_filter`: Neither molecule_chembl_id nor target_chembl_id was supplied, so the query had nothing to scope to. `contradictory_potency_filter`: pchembl_value_min was supplied alongside potency_view \"null_potency\", whose rows have no pchembl_value for the floor to compare against — the combination can only ever match zero measurements. `canvas_capacity_exhausted`: The view spilled with no canvas_id supplied, and the tenant already holds as many canvases as CANVAS_MAX_CANVASES_PER_TENANT allows, so none could be minted to stage it. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "not_found",
-  "rate_limited",
-  "missing_filter",
-  "contradictory_potency_filter"
-]New value: +[
+  "not_found",
+  "rate_limited",
+  "missing_filter",
+  "contradictory_potency_filter",
+  "canvas_capacity_exhausted"
+]

addedOutput schema / properties / nextCursor

Added value: +{
+  "description": "Opaque token for the next page of this view — pass it back as cursor with the same filters and potency_view. Minted only when nothing was staged and rows remain past this page: with the canvas disabled, on a cursor page, or when the view fit inline with no canvas_id supplied. Absent on the last page and whenever the call staged a table (a spill, or an inline fit re-staged on a supplied canvas_id).",
+  "type": "string"
+}

changedOutput schema / properties / notice / description

Previous value: -"Guidance when no measurements matched, or how to SQL the spilled set."New value: +"Guidance when no measurements matched, how to SQL the staged set, or which rows of the view an inline page holds and how to continue it."

changedOutput schema / properties / spilled / description

Previous value: -"True when the view exceeded the preview and was staged on the canvas."New value: +"True when the view exceeded the inline preview and spilled to the canvas. False when it fit inline — including an inline fit re-staged on a supplied canvas_id, which table_name and staged_row_count report."

changedOutput schema / properties / staged_row_count / description

Previous value: -"Rows actually registered on the canvas table. Null when nothing spilled. Below the view total when truncated is true."New value: +"Rows actually registered on the canvas table — 0 when a re-staged view matched nothing. Null when nothing was staged. Below the view total when truncated is true."

changedOutput schema / properties / table_name / description

Previous value: -"Canvas table name holding the staged rowset, and the FROM target for chembl_dataframe_query SQL — \"bioactivities\" for potency_ranked, \"bioactivities_null_potency\" for null_potency. Null when not spilled."New value: +"Canvas table name holding the staged rowset, and the FROM target for chembl_dataframe_query SQL — \"bioactivities\" for potency_ranked, \"bioactivities_null_potency\" for null_potency. Null when nothing was staged."

changedOutput schema / properties / truncated / description

Previous value: -"True when the CHEMBL_MAX_SPILL_ROWS cap was hit before the upstream view was exhausted — the staged table is a bounded slice, NOT the complete view, so aggregates over it are a sample. Narrow the filters to bring the view under the cap."New value: +"True when a bound stopped the page walk short of the view — the CHEMBL_MAX_SPILL_ROWS row cap or the CHEMBL_SPILL_DEADLINE_MS time budget, as truncated_by says. The staged table is then a bounded slice, NOT the complete view, so aggregates over it are a sample. Narrow the filters to bring the view under the bound."

addedOutput schema / properties / truncated_by

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "row_cap",
+        "time_budget"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "The bound that cut the staged table short when truncated is true: \"row_cap\" — the CHEMBL_MAX_SPILL_ROWS cap; \"time_budget\" — the CHEMBL_SPILL_DEADLINE_MS budget ended the page walk, at its expiry or once what was left would not hold another page, so a re-call can stage more. Null when truncated is false."
+}

Changed2 schema fields changedSep 26, 2026

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `missing_filter`: Neither molecule_chembl_id nor target_chembl_id was supplied, so the query had nothing to scope to. `contradictory_potency_filter`: pchembl_value_min was supplied alongside potency_view \"null_potency\", whose rows have no pchembl_value for the floor to compare against — the combination can only ever match zero measurements. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `not_found`: ChEMBL has no record for the requested identifier or structure. `rate_limited`: ChEMBL rate-limits the upstream request. `missing_filter`: Neither molecule_chembl_id nor target_chembl_id was supplied, so the query had nothing to scope to. `contradictory_potency_filter`: pchembl_value_min was supplied alongside potency_view \"null_potency\", whose rows have no pchembl_value for the floor to compare against — the combination can only ever match zero measurements. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "missing_filter",
-  "contradictory_potency_filter"
-]New value: +[
+  "not_found",
+  "rate_limited",
+  "missing_filter",
+  "contradictory_potency_filter"
+]

Changed43 schema fields changedSep 19, 2026
- addedInput schema / properties / canvas_id / pattern
```
Added value: +"^[A-Za-z0-9_-]{10}$"
```
- removedOutput schema / properties / activities / items / properties / assay_description / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / activities / items / properties / assay_description / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / activities / items / properties / assay_type / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / activities / items / properties / assay_type / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / activities / items / properties / molecule_pref_name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / activities / items / properties / molecule_pref_name / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / activities / items / properties / pchembl_value / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / activities / items / properties / pchembl_value / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / activities / items / properties / relation / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / activities / items / properties / relation / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / activities / items / properties / standard_relation / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / activities / items / properties / standard_relation / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / activities / items / properties / standard_type / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / activities / items / properties / standard_type / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / activities / items / properties / standard_units / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / activities / items / properties / standard_units / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / activities / items / properties / standard_value / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / activities / items / properties / standard_value / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / activities / items / properties / target_organism / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / activities / items / properties / target_organism / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / activities / items / properties / target_pref_name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / activities / items / properties / target_pref_name / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / activities / items / properties / type / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / activities / items / properties / type / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / activities / items / properties / units / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / activities / items / properties / units / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / activities / items / properties / value / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / activities / items / properties / value / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / appliedFilters / properties / assay_type / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / appliedFilters / properties / assay_type / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / appliedFilters / properties / organism / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / appliedFilters / properties / organism / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / appliedFilters / properties / pchembl_value_min / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / appliedFilters / properties / pchembl_value_min / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / appliedFilters / properties / standard_type / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / appliedFilters / properties / standard_type / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / canvas_id / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / canvas_id / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / staged_row_count / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / staged_row_count / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / table_name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / table_name / type
```
Added value: +[
+  "string",
+  "null"
+]
```

Changed6 schema fields changedAug 25, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "activities",
+      "totalCount",
+      "potency_view",
+      "spilled",
+      "canvas_id",
+      "table_name",
+      "staged_row_count",
+      "truncated",
+      "canvasDisabled",
+      "appliedFilters"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `missing_filter`: Neither molecule_chembl_id nor target_chembl_id was supplied, so the query had nothing to scope to. `contradictory_potency_filter`: pchembl_value_min was supplied alongside potency_view \"null_potency\", whose rows have no pchembl_value for the floor to compare against — the combination can only ever match zero measurements. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "missing_filter",
+            "contradictory_potency_filter"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "activities",
-  "totalCount",
-  "potency_view",
-  "spilled",
-  "canvas_id",
-  "table_name",
-  "staged_row_count",
-  "truncated",
-  "canvasDisabled",
-  "appliedFilters"
-]

First observedAug 13, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare read-only, open-world, and idempotent behavior, but the description adds substantial operational detail: canvas staging and overwrite semantics, spill row caps and time budgets, truncation flags, cursor pages never being staged, and the inline cap versus totalCount. Nothing contradicts the annotations.

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?

The description front-loads the core purpose and the at-least-one-ID constraint, which is effective. It is necessarily dense for a 12-parameter tool with canvas and cursor behavior, but several sentences are long and run together, reducing scannability.

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

Completeness5/5

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

It covers all critical behavior for this complex tool: selection modes, filters, potency views, alternate forms, canvas staging, pagination, truncation, and totalCount versus inline rows. Return-value shape is handled by the output schema, so the description is complete enough for correct invocation.

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?

With 100% schema description coverage, the schema already carries most parameter meaning. The description still adds useful semantics, such as mixing IC50 and Ki being a scientific error, the rationale for potency_view partitioning, cursor filter consistency, and alternate-form family widening; it is not quite a 5 because much of the per-parameter detail is already present in the schema.

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

Purpose5/5

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

It states a specific verb and resource: bioactivity measurements for a molecule, a target, or a molecule–target pair, and maps each mode to target deconvolution/selectivity or lead finding. It also distinguishes itself from sibling search tools by naming them as ID sources and from dataframe tools by pointing to them for staged results.

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

Usage Guidelines5/5

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

The description explicitly says to supply at least one of molecule_chembl_id or target_chembl_id, that supplying both narrows to the pair, and that supplying neither is an error. It further explains when to use standard_type, potency_view, include_alternate_forms, and cursor, giving clear operational guidance.

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

All chembl-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

chembl-get-bioactivities

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources