GoodbyeMatrix Residency & Citizenship Index

Get programme details

get_program

Read-onlyIdempotent

Returns one programme of the index in detail. Residency programmes: minimum amount and investment options, physical presence, time to permanent residency and to citizenship, dual citizenship, settlement area, tax system of the country, steps and excerpts of the GoodbyeMatrix programme texts (overview, qualification, costs, benefits, citizenship timeline, legal basis). Citizenship by investment programmes: routes with starting amounts, visa-free destinations, status (cost calculator, on request, coming soon or closed) and official links. Includes the programme page in German and English, 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
`id`	Yes	Programme id from search_programs or get_country_overview, or a programme name (word order and country codes are tolerated).
`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
`program`	Yes	The programme; null when the name matches several programmes (see candidates).
`language`	Yes
`candidates`	No	Only when the name matches several programmes: up to 5 matching programmes with their ids.
`cbiQuoteNote`	No	Only for the 9 programmes with a cost calculator: get_cbi_quote calculates the costs for a specific family.
`consultationNote`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 25, 2026

addedOutput schema / properties / program / 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 / program / 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"
+  ]
+}

Changed6 schema fields changedOct 19, 2026

changedInput schema / properties / id / 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 / candidates

Added value: +{
+  "description": "Only when the name matches several programmes: up to 5 matching programmes with their ids.",
+  "items": {
+    "properties": {
+      "country": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "id": {
+        "type": "string"
+      },
+      "name": {
+        "type": "string"
+      },
+      "typeLabel": {
+        "type": "string"
+      }
+    },
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / program / description

Added value: +"The programme; null when the name matches several programmes (see candidates)."

addedOutput schema / properties / program / properties / yearsToCitizenship

Added value: +{
+  "description": "Shortest published number of years to citizenship.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

addedOutput schema / properties / program / properties / yearsToCitizenshipText

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

changedOutput schema / properties / program / type

Previous value: -"object"New value: +[
+  "object",
+  "null"
+]

Changed1 schema field changedOct 19, 2026

changedOutput schema / properties / program / 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.6/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the bar is lower, but the description still adds real context: it clarifies that the tool 'computes from the GoodbyeMatrix data set', stores nothing, sends nothing and calls no external services, and it notes the source date and consultationNote in the payload. It stops short of mentioning latency, caching, or failure behavior for unknown ids.

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?

Front-loaded and organized by programme type, but the long enumeration of returned fields (overview, qualification, costs, benefits, citizenship timeline, legal basis) is largely duplicated by the output schema. The trailing read-only sentence repeats the annotation hints, adding length without much new selection value.

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 an output schema present, the description need not explain return values, yet it still sketches the payload shape and states the language and source-date fields, which helps an agent decide whether to call it. Only the absence of sibling routing and unknown-id behavior keeps it from a 5.

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% and both parameters are fully documented in the schema, including the enum and default for language. The description adds no syntax or format guidance for 'id' beyond what the schema already says, so the baseline 3 applies.

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?

Opens with a specific verb and resource ('Returns one programme of the index in detail') and then breaks down exactly what that means for the two programme categories. It never names a sibling (get_country_overview, compare_programs, search_programs) so the boundary between 'one programme in detail' and the country-level or comparison tools is left implicit.

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: the detail-oriented phrasing plus the schema note that ids come from search_programs or get_country_overview suggests a follow-up call after discovery. There is no explicit statement of when to prefer this over compare_programs or get_country_overview, and no exclusions or prerequisites.

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?