whodb-cli

Official

Overview Schema Source Related Servers Discussions Admin

whodb_platform_source_test

Read-onlyIdempotent

Tests a saved or draft hosted WhoDB source connection before use, validating an existing source or connection fields with optional workspace targeting.

Instructions

Test a hosted WhoDB source connection.

Pass source to test an existing saved source. Omit source and pass source_type plus connection fields to test a draft config without saving it. Accepts workspace {host, org, project} for per-call targeting without changing defaults.

Input Schema

Name	Required	Description
`port`	No
`source`	No	Saved hosted source id or name. If omitted, source_type and config fields test a draft source.
`advanced`	No
`database`	No
`hostname`	No
`password`	No
`username`	No
`workspace`	No	Optional target for this call only. Omit to use the session default set by whodb_platform_session_use, then process/saved defaults. Discover targets with whodb_platform_hosts, whodb_platform_orgs and whodb_platform_projects.
`source_type`	No	Hosted source type id for draft connection tests

Output Schema

Name	Required	Description
`error`	No
`scope`	No
`source`	No
`status`	No
`commands`	No
`recovery`	No
`retryable`	No
`workspace`	No	Optional target for this call only. Omit to use the session default set by whodb_platform_session_use, then process/saved defaults. Discover targets with whodb_platform_hosts, whodb_platform_orgs and whodb_platform_projects.
`error_code`	No
`next_steps`	No
`request_id`	No
`source_type`	No
`setup_status`	No
`suggested_tools`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.136.0Oct 23, 2026

addedOutput schema / properties / error_code
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / recovery

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "LikelyCause": {
+      "type": "string"
+    },
+    "NextSteps": {
+      "items": {
+        "type": "string"
+      },
+      "type": [
+        "null",
+        "array"
+      ]
+    }
+  },
+  "required": [
+    "LikelyCause",
+    "NextSteps"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / retryable
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / suggested_tools

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Addedv0.135.0Oct 15, 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, but the description adds genuinely non-obvious behavior: a draft test does not persist the config, and the workspace argument targets a single call without mutating session defaults. It does not mention connectivity side effects (network egress, timeouts) or what a failure looks like, keeping it below 5.

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?

Three short, front-loaded sentences with no filler; the primary action comes first and the two modes follow immediately. The workspace sentence is a bit dense but carries real information, so nothing meaningful is wasted.

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?

Output schema exists, so return values need not be described, and the dual-mode logic plus workspace override are covered. Given a network-touching, 9-parameter tool with zero required parameters, it could still say whether credentials or an existing session are needed before testing, which leaves a small gap.

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 only 33%; hostname, port, database, username, password and advanced are undocumented in both schema and description. The description adds the useful semantic that these are "connection fields" used only in draft mode, but it does not name or explain them, so it only partially compensates for the coverage gap.

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?

States a specific verb and resource ("Test a hosted WhoDB source connection") and enumerates the two operating modes: testing a saved source vs. a draft config. It never contrasts itself with siblings like whodb_platform_source_create or whodb_platform_source_update, which likely also validate connection details, so the differentiation is implicit rather than explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete when-to-use conditions for both branches: pass `source` for an existing saved source, omit it and pass `source_type` plus connection fields to test a draft. No exclusions or prerequisites (auth requirements, when to prefer create-then-test) are stated, so it stops short of a 5.

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

Deploy Server