companies-house-screening-mcp

Get an officer’s appointments

get_officer_appointments

Read-onlyIdempotent

Retrieve every company an officer currently or previously serves, uncovering undeclared shared directorships and dissolved-company histories. Uses an officer ID from get_officers or find_officer.

Instructions

Every company an officer is or has been appointed to. This is the conflict-of-interest and director-network tool: run it across a board to find the shared directorship nobody declared, or across one person to see whether they have a history of dissolved companies. Needs an officer_id, which comes from get_officers or find_officer and never from a name.

Input Schema

TableJSON Schema

Name	Required	Description
`verbose`	No	Also return the untouched Companies House payload under `raw`, alongside the shaped result. Roughly two and a half times the size; use it only when a field you need is missing from the shaped result.
`officer_id`	Yes	Officer identifier from get_officers or find_officer, not a person’s name.
`start_index`	No	Zero-based offset into the full result set. Use pagination.has_more to decide.
`items_per_page`	No	How many records to return. Defaults to the API default; the maximum is 100.

Output Schema

TableJSON Schema

Name	Required	Description
`raw`	No	The untouched Companies House payload. Present only when verbose was true.
`meta`	Yes	Provenance and budget for this answer.
`name`	No
`officer_id`	Yes
`pagination`	Yes	Where this page sits in the full result set.
`appointments`	Yes
`date_of_birth`	No
`active_appointment_count`	Yes	Derived from the returned page, not the whole set.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.4.0Sep 5, 2026

changedOutput schema / properties / meta / properties / licence / description

Previous value: -"Companies House data is Open Government Licence v3.0."New value: +"OGL v3.0 applies to eligible public-sector information. Personal data and other OGL exclusions are not licensed by this label; applicable data-protection duties still apply."

First observedv0.2.0Aug 30, 2026

TDQS

A4.5/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 the description adds behavior beyond that: the result includes both current and historical appointments ('is or has been appointed to') and is suited for spotting dissolved-company history. No annotation contradiction exists.

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 tightly written sentences: core function, illustrative use cases, and the key input requirement. Every sentence contributes new information and the most important facts are front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list endpoint with a full output schema and fully documented parameters, the description covers the essential context: what data is returned, why an agent would use it, and where the required identifier comes from. Nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema carries most parameter documentation. The description adds important semantic value for officer_id by stating it must come from get_officers or find_officer and not from a name, which prevents a common misuse.

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?

The description states the exact resource ('Every company an officer is or has been appointed to') and positions the tool as the conflict-of-interest/director-network lookup. This clearly distinguishes it from siblings like get_company or get_officers, which have different scopes.

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?

It gives concrete when-to-use scenarios: running across a board to expose undeclared shared directorships, or checking a person's history of dissolved companies. It does not explicitly list sibling alternatives or exclusion conditions, but the use-case framing is clear enough to route an agent correctly.

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

Deploy Server