Compare residue positions within a human transcript to evaluate missense tolerance, Pfam domain annotations, and variant counts.
Signature: compare_positions(transcript_id, positions, response_mode=).
| Name | Required | Description | Default |
|---|---|---|---|
| positions | Yes | Residues. | |
| response_mode | No | Mode. | |
| transcript_id | Yes | ENST. |
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Changes observed during successful MCP inspections.
v0.3.7Input schema / properties / positions / descriptionPrevious value: -"A batch of 1-based protein residue positions to compare side by side."New value: +"Residues."Input schema / properties / positions / examplesPrevious value: -[
- [
- 175,
- 248,
- 273
- ]
-]New value: +[
+ [
+ 35,
+ 175
+ ]
+]Input schema / properties / positions / items / maximumAdded value: +1000000Input schema / properties / positions / items / minimumAdded value: +1Input schema / properties / response_mode / defaultRemoved value: -"compact"Input schema / properties / response_mode / descriptionPrevious value: -"Verbosity: minimal|compact|standard|full (default compact)."New value: +"Mode."Input schema / properties / response_mode / typeRemoved value: -"string"Input schema / properties / transcript_id / descriptionPrevious value: -"A versioned Ensembl transcript id (the .N version suffix is required), e.g. ENST00000269305.4. Resolve a gene symbol with resolve_transcript first."New value: +"ENST."Input schema / properties / transcript_id / examplesPrevious value: -[
- "ENST00000269305.4"
-]New value: +[
+ "ENST00000269305.9"
+]Output schema / (root)Previous value: -nullNew value: +{
+ "$defs": {
+ "M": {
+ "additionalProperties": false,
+ "patternProperties": {
+ "^(tool|request_id|capabilities_version)$": {
+ "type": "string"
+ },
+ "^data_versions$": {
+ "additionalProperties": false,
+ "minProperties": 8,
+ "patternProperties": {
+ "^(assembly|gencode|uniprot|gnomad|clinvar|pfam|metadome_app|data_doi)$": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "^elapsed_ms$": {
+ "type": "integer"
+ },
+ "^next_commands$": {
+ "items": {
+ "additionalProperties": false,
+ "minProperties": 2,
+ "properties": {
+ "arguments": {
+ "propertyNames": {
+ "pattern": "^(transcript_id|position)$"
+ },
+ "type": "object"
+ },
+ "tool": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "^unsafe_for_clinical_use$": {
+ "const": true
+ }
+ },
+ "required": [
+ "tool",
+ "request_id",
+ "data_versions",
+ "unsafe_for_clinical_use"
+ ],
+ "type": "object"
+ }
+ },
+ "oneOf": [
+ {
+ "additionalProperties": false,
+ "patternProperties": {
+ "^(dropped_summary|transcript_id|recommended_citation|data_currency_caveat)$": {
+ "type": "string"
+ },
+ "^_meta$": {
+ "$ref": "#/$defs/M"
+ },
+ "^comparison$": {
+ "items": {
+ "oneOf": [
+ {
+ "additionalProperties": false,
+ "minProperties": 5,
+ "properties": {
+ "domain_ids": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "protein_pos": {
+ "type": "integer"
+ },
+ "ref_aa": {
+ "type": "string"
+ },
+ "sw_dn_ds": {
+ "type": [
+ "number",
+ "null"
+ ]
+ },
+ "variant_evidence": {
+ "additionalProperties": false,
+ "minProperties": 2,
+ "properties": {
+ "meta_domain_homolog_aggregate": {
+ "additionalProperties": false,
+ "patternProperties": {
+ "^(gnomad|clinvar)$": {
+ "additionalProperties": false,
+ "minProperties": 2,
+ "patternProperties": {
+ "^(variant_count|missense_variant_count)$": {
+ "type": "integer"
+ }
+ },
+ "type": "object"
+ },
+ "^(provenance|scope|reason)$": {
+ "type": "string"
+ },
+ "^available$": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "available",
+ "provenance"
+ ],
+ "type": "object"
+ },
+ "residue_level": {
+ "additionalProperties": false,
+ "minProperties": 1,
+ "properties": {
+ "clinvar": {
+ "additionalProperties": false,
+ "minProperties": 4,
+ "patternProperties": {
+ "^(variant_count|missense_variant_count)$": {
+ "type": "integer"
+ },
+ "^available$": {
+ "const": true
+ },
+ "^provenance$": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "gnomad": {
+ "additionalProperties": false,
+ "minProperties": 2,
+ "properties": {
+ "available": {
+ "const": false
+ },
+ "reason": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+ }
+ },
+ "type": "object"
+ }
+ },
+ "type": "object"
+ }
+ },
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "minProperties": 2,
+ "properties": {
+ "error": {
+ "type": "string"
+ },
+ "protein_pos": {
+ "type": "integer"
+ }
+ },
+ "type": "object"
+ }
+ ]
+ },
+ "type": "array"
+ },
+ "^success$": {
+ "const": true
+ }
+ },
+ "required": [
+ "success",
+ "_meta",
+ "transcript_id",
+ "comparison",
+ "recommended_citation"
+ ]
+ },
+ {
+ "additionalProperties": false,
+ "patternProperties": {
+ "^(message|recovery_action|field|hint)$": {
+ "type": "string"
+ },
+ "^_meta$": {
+ "$ref": "#/$defs/M"
+ },
+ "^allowed_values$": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "^error_code$": {
+ "enum": [
+ "invalid_input",
+ "not_found",
+ "ambiguous_query",
+ "upstream_unavailable",
+ "rate_limited",
+ "internal"
+ ]
+ },
+ "^retryable$": {
+ "type": "boolean"
+ },
+ "^success$": {
+ "const": false
+ }
+ },
+ "required": [
+ "success",
+ "_meta",
+ "error_code",
+ "message",
+ "retryable",
+ "recovery_action"
+ ]
+ }
+ ],
+ "type": "object"
+}v0.3.1Output schema / (root)Previous value: -{
- "additionalProperties": true,
- "properties": {
- "_meta": {
- "additionalProperties": true,
- "type": "object"
- },
- "candidates": {
- "type": "array"
- },
- "comparison": {
- "items": {
- "additionalProperties": true,
- "type": "object"
- },
- "type": "array"
- },
- "data_versions": {
- "additionalProperties": true,
- "type": "object"
- },
- "error_code": {
- "type": "string"
- },
- "field": {
- "type": "string"
- },
- "hint": {
- "type": "string"
- },
- "message": {
- "type": "string"
- },
- "recommended_citation": {
- "type": "string"
- },
- "recovery_action": {
- "type": "string"
- },
- "retryable": {
- "type": "boolean"
- },
- "success": {
- "type": "boolean"
- },
- "transcript_id": {
- "type": "string"
- }
- },
- "required": [
- "success"
- ],
- "type": "object"
-}New value: +nullv0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation declares readOnlyHint=true, so the agent knows it's a safe read operation. However, the description adds no behavioral context beyond that—no return format, no side effects, no performance notes. Since annotations already cover the safety aspect, the description contributes nothing extra.
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 line that merely reproduces the signature. It is not appropriately sized because it conveys no information beyond what is already visible in the schema. There is no front-loading of key information; it is essentially a placeholder.
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 (three parameters, an output schema, and many siblings), the description is wholly inadequate. An agent has no idea what the tool compares, how the response modes differ, or what output to expect. The description fails to provide the minimal context needed for correct usage.
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?
While schema_description_coverage is 100%, the parameter descriptions are extremely minimal: 'Residues.', 'Mode.', 'ENST.'—these provide almost no semantic meaning. The tool description itself adds nothing to clarify what these parameters represent or how they relate to the operation. The description fails to compensate for the poor schema wording.
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 is merely the function signature 'compare_positions(transcript_id, positions, response_mode=)', which restates the tool name and parameter list without stating what the tool actually does. It provides no verb, resource, or outcome, so an agent cannot infer the tool's purpose.
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?
There is no guidance on when to use this tool versus any sibling like get_position_tolerance or get_tolerance_landscape. The description offers no context, prerequisites, or exclusions, leaving the agent to guess.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.