Skip to main content
Glama

copy_number_segment

Read-only

Segment one chromosome of an Affymetrix copy-number container by up to four independent methods and report where they agree.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "copy_number_segment"
  }
}

Input Schema

NameRequiredDescriptionDefault
fileNowhich copy-number file in this project, by name. Unset, it is the project's only one — and it refuses rather than guessing when there is more than one.
graphNowhich graph column to segment. Unset is the first log2-ratio column, which is what the panel segments. A column that is not a log2 ratio is refused rather than segmented: a copy-number STATE column is already someone's answer.
_filesNoThe project: record references shaped like _subject. Their records become library documents a tool names in sequences/parts/document; a trace or alignment is found by file name.
pelt_qNochangepoint's `Q`: BinSeg's most change points, SegNeigh's most segments. Read only by those two. Same default as the panel. Only applies when pelt_method is BinSeg or SegNeigh.
cbs_etaNoDNAcopy's `eta`: the error budget for stopping each permutation test early once its outcome is settled. Not the significance level; any value but 0.05 recomputes the stopping boundary. Same default as the panel.
methodsNowhich methods to run, comma-separated: `hmm`, `cbs`, `pcf`, `pelt`. Unset runs all four, because the point of this node is where they agree. The panel has each of them off until asked, so running one here is not a different default — it is the same control, pressed.
_subjectNoThe record to act on: exactly one of sequence, accession (+source), sample (an id from list_samples) or file ({name, text} or {name, base64}); record_index picks one record of several.
cbs_seedNoCBS accepts a boundary by permutation test, so the run is seeded and about 1 borderline dataset in 40 segments differently under a different seed. Same default as the panel.
cbs_trimNoDNAcopy's `trim`: the fraction cut from each tail before sdundo measures the noise SD. Read only when `cbs_undo_splits` is sdundo. Same default as the panel. Only applies when cbs_undo_splits is sdundo.
data_setNowhich data set to segment, by name. Unset is the file's FIRST, which is what the panel opens on.
pcf_kminNoPCF's shortest allowed segment, in markers — the finest change the fit may claim. Same default as the panel.
hmm_modelNowhich copy-number state model the HMM calls against. `file` is the model the container's own header states, and is used when unset if the file states one; otherwise the first preset. `apt-cn-state` is APT's generic method with its GC-corrected means, `apt-cn-cyto2` the six-state method written for CytoScan arrays. The panel lists the same models in the same order. Values: file (This file’s own parameters), apt-cn-state (APT cn-state (GC-corrected)), apt-cn-cyto2 (APT cn-cyto2 (CytoScan)).
pcf_gammaNoPCF's penalty per jump — how much evidence a level change must carry. Scaled by the squared MAD noise estimate unless `pcf_normalize` is off, which is what makes 40 mean the same thing on a quiet array and a noisy one. Same default as the panel.
chromosomeNowhich chromosome to segment, as the file numbers them (1-22, then 23=X, 24=Y, 25=MT — the file's own convention). Unset is the first the index carries, which is what the panel selects.
pcf_methodNowhich piecewise-constant fit: `auto` (copynumber's own rule — the exact dynamic program under 400 markers, its selectFastPcf approximation above), `exact`, or `fast`. Both are graded against R, so this is a real choice. `exact` is refused above 25,000 markers rather than silently downgraded: it is quadratic there (21 s at 100,000), where the approximation fits a whole 142,000-marker chromosome in about 0.3 s. Same default as the panel. Values: auto (Automatic), exact (Exact), fast (Approximate).auto
cbs_undo_sdNoDNAcopy's `undo.SD`: the merge threshold in trimmed noise SDs. Read only when `cbs_undo_splits` is sdundo. Same default as the panel. Only applies when cbs_undo_splits is sdundo.
pelt_methodNowhich of changepoint's three multiple-change searches the `pelt` method runs over the same costs and penalties: `PELT` prunes to the exact optimum in linear time (changepoint's default); `BinSeg` splits greedily, at most `pelt_q` times, keeping each split while it pays for its penalty; `AMOC` scans for at most one change and keeps it only if it pays for the penalty, reporting Chen & Gupta's confidence; `SegNeigh` finds the exact optimum for every segment count up to `pelt_q` and lets the penalty pick one, at quadratic cost, so it declines past a Q·n² work budget (5,000 markers at Q = 5) and refuses MBIC and a shortest segment above 1, as changepoint does. Same default as the panel. Values: PELT (Pruned exact linear time), BinSeg (Binary segmentation), SegNeigh (Segment neighborhood), AMOC (At most one change).PELT
pelt_penaltyNoPELT's penalty, and the reason its knob is a different KIND of knob from PCF's gamma: it is an information criterion, so the number of segments follows from a model-selection rule rather than from a constant calibrated against this array's noise. MBIC is changepoint's own default and adds log(segment length) to each segment's cost as well as its (parameters + 2)·log(n) penalty. `Manual` is the only one that reads `pelt_penalty_value`; `CROPS` is a RANGE (Haynes, Eckley & Fearnhead 2017), read from `pelt_crops_*`, and needs `pelt_method` PELT. Same default as the panel. Values: MBIC (MBIC), BIC (BIC), SIC0 (BIC without the location term), AIC (AIC), Hannan-Quinn (Hannan-Quinn), Manual (Manual), None (None), CROPS (A range (CROPS)).MBIC
pcf_normalizeNoscale the PCF penalty by the squared MAD noise estimate (the vendor’s `normalize`). Off makes gamma an absolute penalty in squared log2 units, which is a different parameter wearing the same name. Same default as the panel.
pelt_crops_toNothe largest penalty of the CROPS range, in multiples of log(n). Read only when `pelt_penalty` is CROPS. Same default as the panel. Only applies when pelt_penalty is CROPS.
cbs_undo_pruneNoDNAcopy's `undo.prune`: the fractional increase in residual cost pruning may accept. Read only when `cbs_undo_splits` is prune. Same default as the panel. Only applies when cbs_undo_splits is prune.
pelt_minseglenNoPELT's shortest allowed segment, in markers (changepoint's `minseglen`) — the finest change the fit may claim. Same default as the panel.
cbs_undo_splitsNoDNAcopy's `undo.splits`, the post-hoc merge over what CBS found: `none` keeps every significant split, `sdundo` merges adjacent segments whose medians are within `cbs_undo_sd` trimmed SDs (is this boundary bigger than the noise?), `prune` keeps the fewest change points whose cost stays within `cbs_undo_prune` (how few boundaries explain this almost as well?). Same default as the panel. Values: none (Keep every split), sdundo (Merge within SDs), prune (Prune by cost).none
pelt_crops_fromNothe smallest penalty of the CROPS range, in multiples of log(n). changepoint's own range is 1 to 10. Read only when `pelt_penalty` is CROPS. Same default as the panel. Only applies when pelt_penalty is CROPS.
pelt_standardizeNodivide by the robust MAD before fitting. ON by default, and this is the one PELT default that is ours rather than the vendor's, because the vendor documents the assumption and does not enforce it: a change-in-mean cost is a raw residual sum of squares while the penalty is on a log(n) scale, so the two are only commensurate at unit variance. Off, a noisy array buys boundaries it should not and a quiet one buys none, and both look like plausible answers. Same default as the panel.
pelt_crops_draw_atNowhich CROPS segmentation becomes `segments.pelt`: the one optimal at this penalty, in multiples of log(n) (2 is BIC for a change in mean). Every segmentation in the range is in the derivation either way. Same default as the panel. Only applies when pelt_penalty is CROPS.
pelt_penalty_valueNothe cost a boundary must save to be worth buying, in the cost function's own units. Read ONLY when `pelt_penalty` is Manual; the named criteria derive their own from the marker count. Same default as the panel. Only applies when pelt_penalty is Manual.

Output Schema

NameRequiredDescriptionDefault
summaryYeswhat each method answered on this chromosome, generated from the run — never a fixed sentence over a variable outcome
segmentsYesper method, its segments with their marker range, genomic span and level — and for the HMM, the state it called
agreementYeswhere the methods that ran put their boundaries, and which boundaries more than one of them found. This is the reading no single method can produce
derivationYesper method, what it actually used: the model and its means for the HMM, the seed for CBS, kmin and the raw and scaled gamma for PCF — plus each method's published provenance, and the reason where one declined to run

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changed
    • changedInput schema / properties / pcf_method / description
      Previous value: -"which piecewise-constant fit: `auto` (copynumber's own rule — the exact dynamic program under 400 markers, its selectFastPcf approximation above), `exact`, or `fast`. Both are ported and graded against R, so this is a real choice. `exact` is refused above 25,000 markers rather than silently downgraded: it is quadratic there (21 s at 100,000), where the approximation fits a whole 142,000-marker chromosome in about 0.3 s. Same default as the panel. Values: auto (Automatic), exact (Exact), fast (Approximate)."New value: +"which piecewise-constant fit: `auto` (copynumber's own rule — the exact dynamic program under 400 markers, its selectFastPcf approximation above), `exact`, or `fast`. Both are graded against R, so this is a real choice. `exact` is refused above 25,000 markers rather than silently downgraded: it is quadratic there (21 s at 100,000), where the approximation fits a whole 142,000-marker chromosome in about 0.3 s. Same default as the panel. Values: auto (Automatic), exact (Exact), fast (Approximate)."
    • addedInput schema / properties / pelt_crops_draw_at
      Added value: +{
      +  "default": 2,
      +  "description": "which CROPS segmentation becomes `segments.pelt`: the one optimal at this penalty, in multiples of log(n) (2 is BIC for a change in mean). Every segmentation in the range is in the derivation either way. Same default as the panel. Only applies when pelt_penalty is CROPS.",
      +  "minimum": 0,
      +  "type": "number"
      +}
    • addedInput schema / properties / pelt_crops_from
      Added value: +{
      +  "default": 1,
      +  "description": "the smallest penalty of the CROPS range, in multiples of log(n). changepoint's own range is 1 to 10. Read only when `pelt_penalty` is CROPS. Same default as the panel. Only applies when pelt_penalty is CROPS.",
      +  "minimum": 0,
      +  "type": "number"
      +}
    • addedInput schema / properties / pelt_crops_to
      Added value: +{
      +  "default": 10,
      +  "description": "the largest penalty of the CROPS range, in multiples of log(n). Read only when `pelt_penalty` is CROPS. Same default as the panel. Only applies when pelt_penalty is CROPS.",
      +  "minimum": 0,
      +  "type": "number"
      +}
    • addedInput schema / properties / pelt_method
      Added value: +{
      +  "default": "PELT",
      +  "description": "which of changepoint's three multiple-change searches the `pelt` method runs over the same costs and penalties: `PELT` prunes to the exact optimum in linear time (changepoint's default); `BinSeg` splits greedily, at most `pelt_q` times, keeping each split while it pays for its penalty; `AMOC` scans for at most one change and keeps it only if it pays for the penalty, reporting Chen & Gupta's confidence; `SegNeigh` finds the exact optimum for every segment count up to `pelt_q` and lets the penalty pick one, at quadratic cost, so it declines past a Q·n² work budget (5,000 markers at Q = 5) and refuses MBIC and a shortest segment above 1, as changepoint does. Same default as the panel. Values: PELT (Pruned exact linear time), BinSeg (Binary segmentation), SegNeigh (Segment neighborhood), AMOC (At most one change).",
      +  "enum": [
      +    "PELT",
      +    "BinSeg",
      +    "SegNeigh",
      +    "AMOC"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / pelt_penalty / description
      Previous value: -"PELT's penalty, and the reason its knob is a different KIND of knob from PCF's gamma: it is an information criterion, so the number of segments follows from a model-selection rule rather than from a constant calibrated against this array's noise. MBIC is changepoint's own default and adds log(segment length) to each segment's cost as well as its (parameters + 2)·log(n) penalty. `Manual` is the only one that reads `pelt_penalty_value`. Same default as the panel. Values: MBIC (MBIC), BIC (BIC), SIC0 (BIC without the location term), AIC (AIC), Hannan-Quinn (Hannan-Quinn), Manual (Manual), None (None)."New value: +"PELT's penalty, and the reason its knob is a different KIND of knob from PCF's gamma: it is an information criterion, so the number of segments follows from a model-selection rule rather than from a constant calibrated against this array's noise. MBIC is changepoint's own default and adds log(segment length) to each segment's cost as well as its (parameters + 2)·log(n) penalty. `Manual` is the only one that reads `pelt_penalty_value`; `CROPS` is a RANGE (Haynes, Eckley & Fearnhead 2017), read from `pelt_crops_*`, and needs `pelt_method` PELT. Same default as the panel. Values: MBIC (MBIC), BIC (BIC), SIC0 (BIC without the location term), AIC (AIC), Hannan-Quinn (Hannan-Quinn), Manual (Manual), None (None), CROPS (A range (CROPS))."
    • changedInput schema / properties / pelt_penalty / enum
      Previous value: -[
      -  "MBIC",
      -  "BIC",
      -  "SIC0",
      -  "AIC",
      -  "Hannan-Quinn",
      -  "Manual",
      -  "None"
      -]New value: +[
      +  "MBIC",
      +  "BIC",
      +  "SIC0",
      +  "AIC",
      +  "Hannan-Quinn",
      +  "Manual",
      +  "None",
      +  "CROPS"
      +]
    • addedInput schema / properties / pelt_q
      Added value: +{
      +  "default": 5,
      +  "description": "changepoint's `Q`: BinSeg's most change points, SegNeigh's most segments. Read only by those two. Same default as the panel. Only applies when pelt_method is BinSeg or SegNeigh.",
      +  "minimum": 1,
      +  "type": "number"
      +}
  2. First observed

TDQS

A3.7/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds the key behavioral point that it reports where up to four independent methods agree, but it does not elaborate on return structure, failure modes, or computational limits beyond what the detailed schema and output schema provide.

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

Conciseness5/5

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

It is a single front-loaded sentence with no filler. Every phrase—chromosome scope, Affymetrix container, four independent methods, agreement report—earns its place.

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

Completeness3/5

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

The tool is complex with 27 parameters, nested objects, and an output schema, and the description gives only the core operation. Given the exhaustive schema and output schema, this is minimally adequate, but the description could better explain when the tool is appropriate and what the agreement report represents.

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

Parameters3/5

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

Schema description coverage is 100%, so every parameter is already thoroughly documented in the input schema. The description mentions 'up to four independent methods' but does not add parameter-level meaning beyond what the schema provides, making the baseline 3 appropriate.

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?

The description states a specific verb ('Segment'), resource ('one chromosome of an Affymetrix copy-number container'), and scope ('by up to four independent methods and report where they agree'). This is clearly distinct from sibling tools like copy_number_read, copy_number_regions, and copy_number_findings, which read, summarize regions, or report findings rather than run multi-method segmentation on a chromosome.

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 implied: this is the tool for segmenting a chromosome with one or more methods and comparing their agreement. The description does not explicitly say when to choose it over copy_number_regions, copy_number_findings, or copy_number_read, nor does it provide when-not-to-use guidance or alternatives.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources