Koskamo

Get host connection handoff

koskamo_get_connection_plan

Read-onlyIdempotent

Generate a manual connection handoff for server_id and host_id from supported setup snippets. Pure read; no charges, saved plan, package installation, credentials, or provider actions. Host installation remains unverified.

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": {
      "server_id": "<server_id>",
      "host_id": "<host_id>"
    },
    "name": "koskamo_get_connection_plan"
  }
}

Input Schema

Name	Required	Description	Default
`host_id`	Yes	Client host for the manual connection setup handoff.
`server_id`	Yes	ID or slug of the published directory server.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedNov 4, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "context": {
-        "additionalProperties": false,
-        "properties": {
-          "app_id": {
-            "const": "koskamo",
-            "type": "string"
-          },
-          "environment": {
-            "enum": [
-              "public",
-              "production",
-              "sandbox"
-            ],
-            "type": "string"
-          },
-          "tenant_ref": {
-            "type": "null"
-          },
-          "timezone": {
-            "const": "UTC",
-            "type": "string"
-          }
-        },
-        "required": [
-          "app_id",
-          "tenant_ref",
-          "environment",
-          "timezone"
-        ],
-        "type": "object"
-      },
-      "data": {
-        "additionalProperties": false,
-        "properties": {
-          "blockers": {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "config_artifact_id": {
-            "type": "null"
-          },
-          "configuration": {
-            "anyOf": [
-              {
-                "additionalProperties": false,
-                "properties": {
-                  "content": {
-                    "type": "string"
-                  },
-                  "format": {
-                    "enum": [
-                      "json",
-                      "command"
-                    ],
-                    "type": "string"
-                  },
-                  "instructions": {
-                    "type": "string"
-                  },
-                  "source_url": {
-                    "format": "uri",
-                    "type": "string"
-                  }
-                },
-                "required": [
-                  "format",
-                  "content",
-                  "instructions",
-                  "source_url"
-                ],
-                "type": "object"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "host_id": {
-            "enum": [
-              "Claude Code",
-              "Codex",
-              "Cursor",
-              "Cline",
-              "VS Code",
-              "Gemini CLI",
-              "Claude Desktop",
-              "Windsurf"
-            ],
-            "type": "string"
-          },
-          "install_state": {
-            "enum": [
-              "not_started",
-              "handoff_required",
-              "verified"
-            ],
-            "type": "string"
-          },
-          "required_input_fields": {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "server_id": {
-            "maxLength": 256,
-            "minLength": 1,
-            "type": "string"
-          },
-          "setup_url": {
-            "anyOf": [
-              {
-                "format": "uri",
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "supported_protocol_versions": {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "transport": {
-            "type": "string"
-          },
-          "validation_steps": {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          }
-        },
-        "required": [
-          "server_id",
-          "host_id",
-          "transport",
-          "supported_protocol_versions",
-          "config_artifact_id",
-          "setup_url",
-          "required_input_fields",
-          "validation_steps",
-          "install_state",
-          "configuration",
-          "blockers"
-        ],
-        "type": "object"
-      },
-      "generated_at": {
-        "format": "date-time",
-        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
-        "type": "string"
-      },
-      "kind": {
-        "const": "record",
-        "type": "string"
-      },
-      "next_actions": {
-        "items": {
-          "oneOf": [
-            {
-              "additionalProperties": false,
-              "properties": {
-                "reason": {
-                  "type": "string"
-                },
-                "tool_name": {
-                  "type": "string"
-                },
-                "type": {
-                  "const": "call_tool",
-                  "type": "string"
-                }
-              },
-              "required": [
-                "type",
-                "tool_name",
-                "reason"
-              ],
-              "type": "object"
-            },
-            {
-              "additionalProperties": false,
-              "properties": {
-                "reason": {
-                  "type": "string"
-                },
-                "type": {
-                  "const": "open_url",
-                  "type": "string"
-                },
-                "url": {
-                  "format": "uri",
-                  "type": "string"
-                }
-              },
-              "required": [
-                "type",
-                "url",
-                "reason"
-              ],
-              "type": "object"
-            },
-            {
-              "additionalProperties": false,
-              "properties": {
-                "fields": {
-                  "items": {
-                    "type": "string"
-                  },
-                  "type": "array"
-                },
-                "reason": {
-                  "type": "string"
-                },
-                "type": {
-                  "const": "provide_input",
-                  "type": "string"
-                }
-              },
-              "required": [
-                "type",
-                "fields",
-                "reason"
-              ],
-              "type": "object"
-            },
-            {
-              "additionalProperties": false,
-              "properties": {
-                "reason": {
-                  "type": "string"
-                },
-                "retry_after_ms": {
-                  "maximum": 9007199254740991,
-                  "minimum": 0,
-                  "type": "integer"
-                },
-                "type": {
-                  "const": "wait",
-                  "type": "string"
-                }
-              },
-              "required": [
-                "type",
-                "retry_after_ms",
-                "reason"
-              ],
-              "type": "object"
-            }
-          ]
-        },
-        "type": "array"
-      },
-      "provenance": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "freshness": {
-              "enum": [
-                "fresh",
-                "stale",
-                "unknown"
-              ],
-              "type": "string"
-            },
-            "observed_at": {
-              "anyOf": [
-                {
-                  "format": "date-time",
-                  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "retrieved_at": {
-              "format": "date-time",
-              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
-              "type": "string"
-            },
-            "source_id": {
-              "type": "string"
-            },
-            "source_url": {
-              "format": "uri",
-              "type": "string"
-            },
-            "source_version": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "source_id",
-            "observed_at",
-            "retrieved_at",
-            "freshness"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "request_id": {
-        "type": "string"
-      },
-      "schema_version": {
-        "const": "1.0.0",
-        "type": "string"
-      },
-      "warnings": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "code": {
-              "type": "string"
-            },
-            "field": {
-              "type": "string"
-            },
-            "message": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "code",
-            "message"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      }
-    },
-    "required": [
-      "schema_version",
-      "kind",
-      "request_id",
-      "generated_at",
-      "context",
-      "data",
-      "warnings",
-      "next_actions"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "context": {
-        "additionalProperties": false,
-        "properties": {
-          "app_id": {
-            "const": "koskamo",
-            "type": "string"
-          },
-          "environment": {
-            "enum": [
-              "public",
-              "production",
-              "sandbox"
-            ],
-            "type": "string"
-          },
-          "tenant_ref": {
-            "type": "null"
-          },
-          "timezone": {
-            "const": "UTC",
-            "type": "string"
-          }
-        },
-        "required": [
-          "app_id",
-          "tenant_ref",
-          "environment",
-          "timezone"
-        ],
-        "type": "object"
-      },
-      "data": {
-        "additionalProperties": false,
-        "properties": {
-          "code": {
-            "enum": [
-              "invalid_input",
-              "unauthenticated",
-              "permission_denied",
-              "consent_required",
-              "ambiguous_target",
-              "not_found",
-              "unsupported_capability",
-              "configuration_required",
-              "integration_expired",
-              "stale_data",
-              "version_conflict",
-              "approval_required",
-              "approval_expired",
-              "idempotency_conflict",
-              "rate_limited",
-              "quota_exceeded",
-              "provider_unavailable",
-              "outcome_unknown",
-              "reconciliation_required",
-              "cursor_expired",
-              "artifact_expired",
-              "internal_error"
-            ],
-            "type": "string"
-          },
-          "domain_code": {
-            "type": "string"
-          },
-          "effects": {
-            "enum": [
-              "none",
-              "committed",
-              "partial",
-              "unknown"
-            ],
-            "type": "string"
-          },
-          "field_errors": {
-            "items": {
-              "additionalProperties": false,
-              "properties": {
-                "field": {
-                  "type": "string"
-                },
-                "message": {
-                  "type": "string"
-                }
-              },
-              "required": [
-                "field",
-                "message"
-              ],
-              "type": "object"
-            },
-            "type": "array"
-          },
-          "message": {
-            "type": "string"
-          },
-          "operation_id": {
-            "type": "string"
-          },
-          "retry_after_ms": {
-            "maximum": 9007199254740991,
-            "minimum": 0,
-            "type": "integer"
-          },
-          "retry_strategy": {
-            "enum": [
-              "never",
-              "same_request",
-              "after_delay",
-              "after_correction",
-              "reconcile_first"
-            ],
-            "type": "string"
-          }
-        },
-        "required": [
-          "code",
-          "message",
-          "effects",
-          "retry_strategy"
-        ],
-        "type": "object"
-      },
-      "generated_at": {
-        "format": "date-time",
-        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
-        "type": "string"
-      },
-      "kind": {
-        "const": "error",
-        "type": "string"
-      },
-      "next_actions": {
-        "items": {
-          "oneOf": [
-            {
-              "additionalProperties": false,
-              "properties": {
-                "reason": {
-                  "type": "string"
-                },
-                "tool_name": {
-                  "type": "string"
-                },
-                "type": {
-                  "const": "call_tool",
-                  "type": "string"
-                }
-              },
-              "required": [
-                "type",
-                "tool_name",
-                "reason"
-              ],
-              "type": "object"
-            },
-            {
-              "additionalProperties": false,
-              "properties": {
-                "reason": {
-                  "type": "string"
-                },
-                "type": {
-                  "const": "open_url",
-                  "type": "string"
-                },
-                "url": {
-                  "format": "uri",
-                  "type": "string"
-                }
-              },
-              "required": [
-                "type",
-                "url",
-                "reason"
-              ],
-              "type": "object"
-            },
-            {
-              "additionalProperties": false,
-              "properties": {
-                "fields": {
-                  "items": {
-                    "type": "string"
-                  },
-                  "type": "array"
-                },
-                "reason": {
-                  "type": "string"
-                },
-                "type": {
-                  "const": "provide_input",
-                  "type": "string"
-                }
-              },
-              "required": [
-                "type",
-                "fields",
-                "reason"
-              ],
-              "type": "object"
-            },
-            {
-              "additionalProperties": false,
-              "properties": {
-                "reason": {
-                  "type": "string"
-                },
-                "retry_after_ms": {
-                  "maximum": 9007199254740991,
-                  "minimum": 0,
-                  "type": "integer"
-                },
-                "type": {
-                  "const": "wait",
-                  "type": "string"
-                }
-              },
-              "required": [
-                "type",
-                "retry_after_ms",
-                "reason"
-              ],
-              "type": "object"
-            }
-          ]
-        },
-        "type": "array"
-      },
-      "provenance": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "freshness": {
-              "enum": [
-                "fresh",
-                "stale",
-                "unknown"
-              ],
-              "type": "string"
-            },
-            "observed_at": {
-              "anyOf": [
-                {
-                  "format": "date-time",
-                  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ]
-            },
-            "retrieved_at": {
-              "format": "date-time",
-              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
-              "type": "string"
-            },
-            "source_id": {
-              "type": "string"
-            },
-            "source_url": {
-              "format": "uri",
-              "type": "string"
-            },
-            "source_version": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "source_id",
-            "observed_at",
-            "retrieved_at",
-            "freshness"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "request_id": {
-        "type": "string"
-      },
-      "schema_version": {
-        "const": "1.0.0",
-        "type": "string"
-      },
-      "warnings": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "code": {
-              "type": "string"
-            },
-            "field": {
-              "type": "string"
-            },
-            "message": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "code",
-            "message"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      }
-    },
-    "required": [
-      "schema_version",
-      "kind",
-      "request_id",
-      "generated_at",
-      "context",
-      "data",
-      "warnings",
-      "next_actions"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "context": {
+        "additionalProperties": false,
+        "properties": {
+          "app_id": {
+            "const": "koskamo",
+            "type": "string"
+          },
+          "environment": {
+            "enum": [
+              "public",
+              "production",
+              "sandbox"
+            ],
+            "type": "string"
+          },
+          "tenant_ref": {
+            "type": "null"
+          },
+          "timezone": {
+            "const": "UTC",
+            "type": "string"
+          }
+        },
+        "required": [
+          "app_id",
+          "tenant_ref",
+          "environment",
+          "timezone"
+        ],
+        "type": "object"
+      },
+      "data": {
+        "additionalProperties": false,
+        "properties": {
+          "blockers": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "config_artifact_id": {
+            "type": "null"
+          },
+          "configuration": {
+            "anyOf": [
+              {
+                "additionalProperties": false,
+                "properties": {
+                  "content": {
+                    "type": "string"
+                  },
+                  "format": {
+                    "enum": [
+                      "json",
+                      "command"
+                    ],
+                    "type": "string"
+                  },
+                  "instructions": {
+                    "type": "string"
+                  },
+                  "source_url": {
+                    "format": "uri",
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "format",
+                  "content",
+                  "instructions",
+                  "source_url"
+                ],
+                "type": "object"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "host_id": {
+            "enum": [
+              "Claude Code",
+              "Codex",
+              "Cursor",
+              "Cline",
+              "VS Code",
+              "Gemini CLI",
+              "Claude Desktop",
+              "Windsurf"
+            ],
+            "type": "string"
+          },
+          "install_state": {
+            "enum": [
+              "not_started",
+              "handoff_required",
+              "verified"
+            ],
+            "type": "string"
+          },
+          "required_input_fields": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "server_id": {
+            "maxLength": 256,
+            "minLength": 1,
+            "type": "string"
+          },
+          "setup_url": {
+            "anyOf": [
+              {
+                "format": "uri",
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "supported_protocol_versions": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "transport": {
+            "type": "string"
+          },
+          "validation_steps": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          }
+        },
+        "required": [
+          "server_id",
+          "host_id",
+          "transport",
+          "supported_protocol_versions",
+          "config_artifact_id",
+          "setup_url",
+          "required_input_fields",
+          "validation_steps",
+          "install_state",
+          "configuration",
+          "blockers"
+        ],
+        "type": "object"
+      },
+      "generated_at": {
+        "format": "date-time",
+        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+        "type": "string"
+      },
+      "kind": {
+        "const": "record",
+        "type": "string"
+      },
+      "next_actions": {
+        "items": {
+          "oneOf": [
+            {
+              "additionalProperties": false,
+              "properties": {
+                "reason": {
+                  "type": "string"
+                },
+                "tool_name": {
+                  "minLength": 1,
+                  "type": "string"
+                },
+                "type": {
+                  "const": "call_tool",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "type",
+                "tool_name",
+                "reason"
+              ],
+              "type": "object"
+            },
+            {
+              "additionalProperties": false,
+              "properties": {
+                "reason": {
+                  "type": "string"
+                },
+                "type": {
+                  "const": "open_url",
+                  "type": "string"
+                },
+                "url": {
+                  "format": "uri",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "type",
+                "url",
+                "reason"
+              ],
+              "type": "object"
+            },
+            {
+              "additionalProperties": false,
+              "properties": {
+                "fields": {
+                  "items": {
+                    "type": "string"
+                  },
+                  "type": "array"
+                },
+                "reason": {
+                  "type": "string"
+                },
+                "type": {
+                  "const": "provide_input",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "type",
+                "fields",
+                "reason"
+              ],
+              "type": "object"
+            },
+            {
+              "additionalProperties": false,
+              "properties": {
+                "reason": {
+                  "type": "string"
+                },
+                "retry_after_ms": {
+                  "maximum": 9007199254740991,
+                  "minimum": 0,
+                  "type": "integer"
+                },
+                "type": {
+                  "const": "wait",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "type",
+                "retry_after_ms",
+                "reason"
+              ],
+              "type": "object"
+            }
+          ]
+        },
+        "type": "array"
+      },
+      "provenance": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "freshness": {
+              "enum": [
+                "fresh",
+                "stale",
+                "unknown"
+              ],
+              "type": "string"
+            },
+            "observed_at": {
+              "anyOf": [
+                {
+                  "format": "date-time",
+                  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "retrieved_at": {
+              "format": "date-time",
+              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+              "type": "string"
+            },
+            "source_id": {
+              "minLength": 1,
+              "type": "string"
+            },
+            "source_url": {
+              "format": "uri",
+              "type": "string"
+            },
+            "source_version": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "source_id",
+            "observed_at",
+            "retrieved_at",
+            "freshness"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "request_id": {
+        "minLength": 1,
+        "type": "string"
+      },
+      "schema_version": {
+        "const": "1.0.0",
+        "type": "string"
+      },
+      "warnings": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "field": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      }
+    },
+    "required": [
+      "schema_version",
+      "kind",
+      "request_id",
+      "generated_at",
+      "context",
+      "data",
+      "warnings",
+      "next_actions"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "context": {
+        "additionalProperties": false,
+        "properties": {
+          "app_id": {
+            "const": "koskamo",
+            "type": "string"
+          },
+          "environment": {
+            "enum": [
+              "public",
+              "production",
+              "sandbox"
+            ],
+            "type": "string"
+          },
+          "tenant_ref": {
+            "type": "null"
+          },
+          "timezone": {
+            "const": "UTC",
+            "type": "string"
+          }
+        },
+        "required": [
+          "app_id",
+          "tenant_ref",
+          "environment",
+          "timezone"
+        ],
+        "type": "object"
+      },
+      "data": {
+        "additionalProperties": false,
+        "properties": {
+          "code": {
+            "enum": [
+              "invalid_input",
+              "unauthenticated",
+              "permission_denied",
+              "consent_required",
+              "ambiguous_target",
+              "not_found",
+              "unsupported_capability",
+              "configuration_required",
+              "integration_expired",
+              "stale_data",
+              "version_conflict",
+              "approval_required",
+              "approval_expired",
+              "idempotency_conflict",
+              "rate_limited",
+              "quota_exceeded",
+              "provider_unavailable",
+              "outcome_unknown",
+              "reconciliation_required",
+              "cursor_expired",
+              "artifact_expired",
+              "internal_error"
+            ],
+            "type": "string"
+          },
+          "domain_code": {
+            "type": "string"
+          },
+          "effects": {
+            "enum": [
+              "none",
+              "committed",
+              "partial",
+              "unknown"
+            ],
+            "type": "string"
+          },
+          "field_errors": {
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "field": {
+                  "type": "string"
+                },
+                "message": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "field",
+                "message"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "message": {
+            "type": "string"
+          },
+          "operation_id": {
+            "type": "string"
+          },
+          "retry_after_ms": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "retry_strategy": {
+            "enum": [
+              "never",
+              "same_request",
+              "after_delay",
+              "after_correction",
+              "reconcile_first"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "code",
+          "message",
+          "effects",
+          "retry_strategy"
+        ],
+        "type": "object"
+      },
+      "generated_at": {
+        "format": "date-time",
+        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+        "type": "string"
+      },
+      "kind": {
+        "const": "error",
+        "type": "string"
+      },
+      "next_actions": {
+        "items": {
+          "oneOf": [
+            {
+              "additionalProperties": false,
+              "properties": {
+                "reason": {
+                  "type": "string"
+                },
+                "tool_name": {
+                  "minLength": 1,
+                  "type": "string"
+                },
+                "type": {
+                  "const": "call_tool",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "type",
+                "tool_name",
+                "reason"
+              ],
+              "type": "object"
+            },
+            {
+              "additionalProperties": false,
+              "properties": {
+                "reason": {
+                  "type": "string"
+                },
+                "type": {
+                  "const": "open_url",
+                  "type": "string"
+                },
+                "url": {
+                  "format": "uri",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "type",
+                "url",
+                "reason"
+              ],
+              "type": "object"
+            },
+            {
+              "additionalProperties": false,
+              "properties": {
+                "fields": {
+                  "items": {
+                    "type": "string"
+                  },
+                  "type": "array"
+                },
+                "reason": {
+                  "type": "string"
+                },
+                "type": {
+                  "const": "provide_input",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "type",
+                "fields",
+                "reason"
+              ],
+              "type": "object"
+            },
+            {
+              "additionalProperties": false,
+              "properties": {
+                "reason": {
+                  "type": "string"
+                },
+                "retry_after_ms": {
+                  "maximum": 9007199254740991,
+                  "minimum": 0,
+                  "type": "integer"
+                },
+                "type": {
+                  "const": "wait",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "type",
+                "retry_after_ms",
+                "reason"
+              ],
+              "type": "object"
+            }
+          ]
+        },
+        "type": "array"
+      },
+      "provenance": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "freshness": {
+              "enum": [
+                "fresh",
+                "stale",
+                "unknown"
+              ],
+              "type": "string"
+            },
+            "observed_at": {
+              "anyOf": [
+                {
+                  "format": "date-time",
+                  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "retrieved_at": {
+              "format": "date-time",
+              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+              "type": "string"
+            },
+            "source_id": {
+              "minLength": 1,
+              "type": "string"
+            },
+            "source_url": {
+              "format": "uri",
+              "type": "string"
+            },
+            "source_version": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "source_id",
+            "observed_at",
+            "retrieved_at",
+            "freshness"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "request_id": {
+        "minLength": 1,
+        "type": "string"
+      },
+      "schema_version": {
+        "const": "1.0.0",
+        "type": "string"
+      },
+      "warnings": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "field": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      }
+    },
+    "required": [
+      "schema_version",
+      "kind",
+      "request_id",
+      "generated_at",
+      "context",
+      "data",
+      "warnings",
+      "next_actions"
+    ],
+    "type": "object"
+  }
+]

AddedNov 3, 2026

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world. The description adds real value beyond them: no charges, no saved plan, no package installation, no credentials handled, no provider actions, and explicitly that host installation 'remains unverified.' That last clause is important because an agent could otherwise assume the handoff completes setup. It is consistent with readOnlyHint=true, not contradictory.

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?

Three short clauses, front-loaded with the action, then the safety profile, then the limitation. Every phrase carries information — the negative list ('no charges, saved plan, package installation, credentials, or provider actions') is dense rather than padded.

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?

A two-required-parameter read tool with an output schema, rich annotations, and full schema coverage needs little more than this. The only gap is guidance on choosing among related read siblings such as get_connection_health; return values are rightly left to the output schema.

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%, with both parameters described and host_id constrained by an enum, so the schema carries the load. The description reinforces that both IDs come from the directory/'supported setup snippets' but adds no format or lookup guidance beyond that. Baseline 3 is appropriate.

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 uses a specific verb and resource: 'Generate a manual connection handoff' scoped to server_id and host_id. The word 'manual' and 'setup snippets' distinguish it from adjacent siblings like get_connection_health (which checks status) and plan_task. It stops short of naming an alternative, so a 4 rather than a 5.

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 by the phrase 'from supported setup snippets' and by the host enum, but there is no explicit statement of when to call this versus koskamo_get_connection_health or koskamo_get_mcp_server. No when-not conditions or prerequisites are given.

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

All Koskamo 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?