Skip to main content
Glama

Get Gene Mutations

get_gene_mutations
Read-only

Retrieve distinct somatic mutations of one gene in a cBioPortal study, ordered by recurrence, with protein change, samples, mutation type, genomic coordinates, and study licence. Filter by protein change as needed.

Instructions

Get the distinct somatic mutations of one gene in one study, most recurrent first: protein_change, samples, mutation_type and genomic chr/start/end/ref/alt with their assembly (mostly GRCh37), plus mutated_samples and the study's licence and citation. protein_change keeps one change. No sample or patient IDs. Signature: get_gene_mutations(gene, study_id, protein_change=, include_restricted=, response_mode=, limit=, offset=).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "gene": "<gene>",
      "study_id": "<study_id>"
    },
    "name": "get_gene_mutations"
  }
}

Input Schema

NameRequiredDescriptionDefault
geneYesGene symbol (HGNC, e.g. BRAF) or NCBI Gene ID (673 or NCBIGene:673).
limitNoMax rows (default 20, max 100).
offsetNoRows to skip; use the previous `next_offset`.
study_idYescBioPortal study ID (from search_studies).
response_modeNominimal: protein change and samples | compact (default): + type and genomic coordinates | standard/full: + variant type, RefSeq transcript, protein position, keyword.
protein_changeNoOne-letter protein change, e.g. V600E or G12C (p. prefix optional).
include_restrictedNoOpt in to studies with non-commercial/no-derivatives terms (flagged).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already declare readOnlyHint and openWorldHint, so the description's added value is real: it discloses result ordering (most recurrent first), a data limitation (no sample or patient IDs), the coordinate assembly caveat (mostly GRCh37), the inclusion of licence/citation, and that restricted studies are flagged. That is substantive context beyond the annotations, though it stops short of noting pagination behavior or result-size expectations.

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

Conciseness3/5

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

The opening sentence is dense and front-loads the useful return-field and ordering information, but it packs caveats parenthetically and then appends a full signature listing all seven parameters, which is pure repetition of the input schema. Trimming the signature would sharpen the definition without losing information.

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?

With seven parameters, no output schema, and an enumerating first sentence, the description is largely sufficient: it tells the agent what comes back, in what order, and what is excluded. The remaining gap is modest — nothing about how many results to expect or how limit/offset interact with the returned next_offset, which the schema only partly covers.

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 100%, so the baseline is 3, but the description adds genuine meaning by explaining that 'protein_change keeps one change', resolving how that filter collapses multi-change variants. The trailing signature line merely restates parameters the schema already documents, which dilutes but does not erase the added semantics.

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?

The description states a specific verb and resource ('Get the distinct somatic mutations of one gene in one study') and pins down scope plus return fields (protein_change, samples, mutation_type, genomic coordinates, licence/citation). It is immediately clear this is gene-level mutation retrieval rather than frequency or count summaries, though it never names a sibling tool to contrast with.

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: 'one gene in one study', 'most recurrent first', and 'No sample or patient IDs' hint that per-sample or aggregate-frequency work belongs elsewhere, but no explicit when-to-use or when-not-to-use statement is given. An agent must infer the boundary from the return-field list.

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