GoodbyeMatrix Residency & Citizenship Index

Compare programmes

compare_programs

Read-onlyIdempotent

Sets 2 to 5 programmes of the index side by side: type, country, minimum amount, physical presence, time to permanent residency and to citizenship, path to citizenship, dual citizenship, tax system of the country, visa-free destinations and the programme page in German and English, plus the date of the source and consultationNote. Read-only: it only retrieves and computes from the GoodbyeMatrix data set, stores nothing, sends nothing and calls no external services.

Input Schema

Name	Required	Description	Default
`ids`	Yes	2 to 5 programme ids (as returned by search_programs).
`language`	No	Response language: "en" (English, default) or "de" (German).	en

Output Schema

Name	Required	Description
`ok`	Yes
`tool`	No
`stand`	Yes	Date of the source data (YYYY-MM-DD).
`notice`	Yes	General information, not legal, tax or immigration advice.
`schema`	No
`language`	Yes
`programs`	Yes
`consultationNote`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 25, 2026

addedOutput schema / properties / programs / items / properties / betragsHauptart

Added value: +{
+  "description": "Residency only: main kind of the headline amount: kapital_angelegt (capital invested and kept), zahlung (payment that is spent: contribution, fee, membership, minimum tax) or nachweis (proof of funds or income). null when not set.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / programs / items / properties / betragsart

Added value: +{
+  "description": "Residency only: kind of the headline amount (minimumAmount or incomeRequirement) as set by GoodbyeMatrix, one of immobilie (property purchase), bankeinlage (bank deposit), anleihen_fonds (bonds or funds), unternehmen (business investment), investition (minimum investment, several routes), staatsbeitrag (government contribution), mitgliedschaft (membership fee), gebuehr (one-time fee), mindeststeuer (minimum tax per year), vermoegen (proof of funds), einkommen (income). null when not set.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

Changed3 schema fields changedOct 19, 2026

changedInput schema / properties / ids / items / description

Previous value: -"Programme id as returned by search_programs or get_country_overview (for example \"portugal__portugal_golden_visa\" or \"grenada\"); a programme name is matched as well."New value: +"Programme id from search_programs or get_country_overview, or a programme name (word order and country codes are tolerated)."

addedOutput schema / properties / programs / items / properties / yearsToCitizenship
```
Added value: +{
+  "type": [
+    "number",
+    "null"
+  ]
+}
```

addedOutput schema / properties / programs / items / properties / yearsToCitizenshipText

Added value: +{
+  "description": "Published wording when the years to citizenship depend on nationality or other conditions.",
+  "type": "string"
+}

Changed1 schema field changedOct 19, 2026

changedOutput schema / properties / programs / items / properties / type / enum

Previous value: -[
-  "citizenship_by_investment",
-  "residence_by_investment",
-  "digital_nomad",
-  "independent_means",
-  "active_investor"
-]New value: +[
+  "citizenship_by_investment",
+  "residence_by_investment",
+  "digital_nomad",
+  "independent_means",
+  "active_investor",
+  "skilled_work"
+]

First observedOct 19, 2026

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description reinforces this with concrete operational context ('retrieves and computes from the GoodbyeMatrix data set, stores nothing, sends nothing and calls no external services'), though it could say more about computation or freshness beyond the source date.

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?

Front-loaded with the core action and scope, followed by a compact behavioral disclaimer. The attribute list is long but earns its place by defining output relevance; no filler sentences.

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 a full output schema, rich input schema, and comprehensive annotations, the description is complete enough for correct invocation. A minor gap is that it does not relate the language parameter to the returned programme-page fields.

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 coverage is 100%, so both parameters are fully documented in the schema. The description adds only the 2-to-5 programme constraint, which the schema already enforces via minItems/maxItems, and does not clarify the language parameter's effect on response content.

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?

States a specific verb and resource ('Sets 2 to 5 programmes ... side by side') and enumerates the compared attributes, clearly distinguishing it from single-programme siblings like get_program and list-oriented search_programs.

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?

The 2-to-5 programme scope implies comparison usage, but the description never explicitly says when to choose this over get_program, list_cbi_programs, or search_programs. Usage is inferable rather than guided.

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

All GoodbyeMatrix Residency & Citizenship Index 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.

Resources

Need Help?