chembl-mcp-server

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

Annotations already indicate read-only and idempotent behavior. The description adds valuable context beyond annotations: it specifies the return format (row count, kind, column names + types) and the prerequisite requirement of CANVAS_PROVIDER_TYPE=duckdb. These details are not present in 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.

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

The description is exactly two sentences, front-loaded with the primary action. It provides its purpose, usage, return details, and a prerequisite without any redundant or filler content. Every sentence earns its place.

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

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

For a tool with one parameter, an output schema, and clear annotations, the description covers purpose, usage context, prerequisites, and return structure. It is complete enough for an agent to select and invoke correctly without further questions.

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

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

The input schema already provides a description for the sole parameter canvas_id ('Canvas ID returned by chembl_get_bioactivities (spilled: true)'), so schema coverage is 100%. The tool description doesn't add additional parameter semantics beyond what the schema already states, so the baseline score of 3 is appropriate.

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

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

The description uses 'List' as a specific verb and clearly identifies the resource as 'tables and columns staged on a canvas by chembl_get_bioactivities'. It distinguishes itself from sibling tools by explicitly referencing chembl_dataframe_query, which is the likely alternative for querying.

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

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

The description explicitly instructs to 'inspect before calling chembl_dataframe_query to write correct SQL', providing a clear workflow and naming the alternative tool. This gives concrete guidance on when to use this tool versus the sibling query tool.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description explains the truncated and rendered_rows fields, the canvas row cap and character budget behaviors, and the CANVAS_PROVIDER_TYPE=duckdb prerequisite. This significantly enriches the agent's understanding of runtime constraints and paging.

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

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

The description is dense but efficiently structured: it leads with the core action, then explains table references, provides an aggregate example, details bound fields with paging instructions, and closes with a prerequisite. Every sentence contributes essential operational knowledge.

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

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

Given the tool's complexity (SQL execution, paging, two independent limits, provider requirement), the description covers all key aspects. Output schema exists, so return fields need not be exhaustively enumerated, but the description already covers truncated/rendered_rows semantics.

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

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

Schema coverage is 100% with clear descriptions for both sql and canvas_id. The description adds value by showing example SQL, explaining how to reference staged tables, and clarifying that canvas_id comes specifically from a spilled result. This goes slightly beyond the schema baseline.

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

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

The description clearly states the tool runs a read-only SQL SELECT over bioactivity rows spilled to a canvas by chembl_get_bioactivities. It specifies the action (rank, group, dedupe, aggregate), the resource (bioactivity rows), and distinguishes from the inline preview and sibling tools like chembl_dataframe_describe.

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

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

The description explicitly positions this tool for full-set analysis beyond inline previews, advises using chembl_dataframe_describe for schema discovery, and provides concrete paging guidance with LIMIT/OFFSET. It also includes an example query showing when to use it for honest aggregates.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description does not need to repeat those. It adds valuable context about the confidence score meaning ('9 = direct assay on the protein target, lower = homologous or indirect') and describes the provenance nature, going beyond the annotations. No contradiction.

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

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

The description is two sentences: the first defines the tool's output, the second gives usage context and an example data flow. It is front-loaded with the core purpose and contains no filler or redundant info.

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

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

The description covers what the tool returns, where the input comes from, and the decision context (comparability assessment). With an output schema present and annotations covering safety traits, this is fully complete for an agent to select and invoke the tool correctly.

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

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

The schema already covers the single parameter with a description and example ('CHEMBL674637'), so schema coverage is 100%. The description reinforces the source of the ID (from chembl_get_bioactivities) but does not add new parameter semantics, justifying the baseline 3.

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

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

The description clearly states the tool's function: 'Assay provenance behind a bioactivity row' and details the specific data returned (description, type, target, organism, confidence score). This is a specific verb+resource combination that distinguishes it from sibling tools like chembl_get_bioactivities or chembl_search_targets.

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

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

It provides explicit usage guidance: 'Supply assay_chembl_id from a chembl_get_bioactivities row' and 'Call this to judge whether two measurements are comparable'. This tells the agent exactly when and how to use the tool, with implied alternative context (using bioactivities first).

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

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

Annotations declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds far more: the pchembl_value split into two views, canvas table staging behavior, the cap at CHEMBL_MAX_SPILL_ROWS, the 'truncated' flag, the limit compared to totalCount, and the duckdb requirement for spilling. It even discloses that re-running the same view overwrites its prior rows. No annotation contradiction exists; the description builds on the annotations with critical runtime behaviors.

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

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

The description is long but every sentence earns its place. It is front-loaded with the core purpose, then methodically covers input requirements, filtering, the pchembl split, and spill behavior. There is no redundancy or fluff; the structure flows from what the tool does, to how to call it, to critical caveats about large result sets.

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

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

With 9 parameters, multiple views, and large-result spill behavior, the description addresses all major decision points: which IDs to supply, how to choose filter values, the two potency views, the distinction between inline preview and staged table, and the role of totalCount/truncated. An output schema exists, so return-value details are not required, but the description still explains the canonical output fields (totalCount, truncated) and how to reconstruct the full set via UNION ALL.

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

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

Schema description coverage is 100%, but the description adds meaning well beyond the schema. It explains the relationship between molecule_chembl_id and target_chembl_id (both narrows to the pair), gives concrete examples for pchembl_value_min ('7 keeps sub-100 nM activities'), clarifies standard_type's scientific necessity, and details the potency_view enum semantics (the null_potency view returns rows otherwise unreachable). This is substantial added value over the schema alone.

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

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

The description opens with a clear, specific statement: 'The flagship compound↔target bioactivity bridge: measurements for a molecule (target deconvolution / selectivity), a target (lead finding), or both together.' This identifies the exact verb (retrieve/list bioactivities) and resource (compound-target bioactivity data), and distinguishes it from sibling tools by defining the three use modes. It also references sibling sources (chembl_search_molecules, chembl_search_targets), further clarifying scope.

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

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

The description provides explicit when-to-use guidance: 'Supply at least one of molecule_chembl_id... or target_chembl_id... supplying both narrows to that compound–target pair, supplying neither is an error.' It also warns against mixing measurement types ('Mixing measurement types (IC50 vs Ki) is a scientific error — set standard_type to compare like with like'), and explains when to use the DataCanvas dataframe tools instead ('results spill to a DataCanvas table (call chembl_dataframe_describe...)'). This is exceptional usage guidance.

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

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

While annotations already declare readOnlyHint and idempotentHint, the description adds critical behavioral nuance: 'an empty mechanisms or indications array means the molecule has none recorded only when the matching mechanisms_status / indications_status is "complete" — "failed" means the upstream request was rejected... and "truncated" means the page cap bounded the list at fewer rows.' This explains how to interpret ambiguous results, going well beyond 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.

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

The description is a single, well-organized paragraph with no filler. Each sentence has a distinct role: purpose, input source, distinction from alternatives, chaining to related tools, and retrieval-state semantics. It is front-loaded with the most important information and remains compact despite its richness.

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

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

Given the tool's moderate complexity, the description covers all essential aspects: what data is returned, how to obtain the required input, how to interpret edge cases (failed/truncated), and how it relates to sibling tools. An output schema exists, so the absence of an explicit return structure is acceptable. The description fully equips an agent to select and use the tool correctly.

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

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

The schema already covers the parameter fully at 100% coverage, so the baseline is 3. The description adds value by specifying the source ('from chembl_search_molecules') and a concrete example ('e.g. "CHEMBL939" for gefitinib'), which helps the agent understand the expected format and provenance. This pushes it to a 4.

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

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

The description opens with 'Pharmacology for a drug (molecule): mechanism(s) of action, the molecular target(s) it acts on, action type (inhibitor / agonist / …), first-approval year, and clinical indications with the max phase reached for each.' This clearly states a specific verb and resource, and even lists the exact data fields. It also distinguishes itself from the openfda label/adverse-event view and from the bioactivities tool, making sibling differentiation clear.

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

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

The description provides explicit usage context: 'Supply molecule_chembl_id (from chembl_search_molecules)' tells the agent where the input comes from, and 'Distinct from the openfda server's label/adverse-event view' tells when not to use this tool. It also gives a follow-up route: 'A mechanism's target_chembl_id chains into chembl_get_bioactivities for compounds hitting the same target,' which is a direct alternative/recommendation.

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

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

The description adds valuable behavioral context beyond the annotations: pagination via `nextCursor` and `cursor`, capped results, the fact that only similarity adds a Tanimoto percentage, and the external constraint that ChEMBL rejects similarity thresholds below 40. This is substantial context not captured by the readOnly/openWorld/idempotent hints.

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

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

The description is compact and front-loaded: it opens with the tool's role, then covers modes, required inputs, output fields, downstream usage, and pagination in four sentences. Every sentence conveys necessary information without redundancy.

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

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

For a tool with 7 parameters and multiple search modes, the description covers the core purpose, input requirements, output content, downstream integration, and pagination behavior. The presence of a rich output schema and full schema parameter descriptions fills in the remaining details, making this a complete and self-sufficient description.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds cross-parameter constraints not fully visible in the schema: 'At least one of query or structure is required' and 'structure is required for the three structure modes.' This clarifies the interrelationship between parameters beyond individual descriptions.

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

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

The description states a specific verb and resource: 'Discovery entry point for compounds' and details the supported search modes (name, exact, similarity, substructure) with input requirements. It clearly distinguishes itself from sibling `chembl_search_targets` by focusing on molecules and compounds.

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

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

The description provides clear context for using the tool: it is the discovery entry point for compounds and explains when to use each search mode. It also suggests downstream chaining to `chembl_get_bioactivities` or `chembl_get_drug_info`. However, it does not explicitly state when not to use the tool or mention alternatives like `chembl_search_targets`.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description carries a lighter burden. It adds meaningful context beyond those hints: pagination behavior (nextCursor and cursor), return fields (type, organism, component accessions/gene symbols), and the precision hierarchy. This is useful operational detail not visible in annotations alone.

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

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

The description is three sentences, each earning its place: purpose + input requirements, return fields, and pagination guidance. It is front-loaded with the purpose and immediately orients the agent. No filler or redundancy.

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

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

With an output schema present, the description does not need to detail return values, and it adequately covers workflow context, required inputs, optional filters, precision advice, and pagination—all critical for correct invocation. It names the dependent sibling tool and clearly explains the continuation token mechanics, making the tool usable end-to-end.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic value by explicitly stating that at least one of accession/gene_symbol/query is required (schema marks all as optional) and flags accession as the 'most precise' resolver. It also clarifies cursor behavior ('same filters' and 'only limit may change'), which enriches the raw schema definitions.

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

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

The opening sentence states a specific verb ('Resolve') with a clear resource (protein/gene/UniProt accession → ChEMBL target ID) and explicitly names the downstream consumer (chembl_get_bioactivities) and workflow (target→leads). This immediately distinguishes it from sibling tools like chembl_search_molecules and chembl_get_bioactivities.

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

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

The description gives concrete usage context: it is required for the target→leads workflow, and specifies input requirements ('Supply at least one of accession, gene_symbol, or query') and optional filters (organism, target_type). It also provides selection advice (UniProt accession is 'the most precise input'). However, it does not explicitly state when not to use this tool or mention alternatives, so it falls short of a 5.

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