Greenhouse MCP

update_department

Change a department's name, parent, or external ID in Greenhouse ATS. Admin-only write; get department_id via list_departments, and omitted names keep the current value.

Instructions

Update a department's name, parent or external ID. Write operation — admin only.

To find department_id: list_departments → match by name. Greenhouse requires the name on every update, so the current name is kept when name is omitted.

Input Schema

Name	Required	Description
`name`	No	New department name
`parent_id`	No	New parent department ID — get from list_departments
`external_id`	No	New HRIS/external identifier
`department_id`	Yes	Department ID to update

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.5.0Oct 5, 2026

addedInput schema / properties / department_id / description
```
Added value: +"Department ID to update"
```

addedInput schema / properties / external_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "New HRIS/external identifier",
+  "title": "External Id"
+}

addedInput schema / properties / name / description
```
Added value: +"New department name"
```

addedInput schema / properties / parent_id / description

Added value: +"New parent department ID — get from list_departments"

Addedv0.3.4Apr 15, 2026

TDQS

A4.4/5.0

Behavior4/5

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

With no annotations, the description carries the full load and delivers the two facts that matter: this is a write operation requiring admin rights, and it is a partial update — Greenhouse requires the name, so the existing name is preserved when name is omitted. Reversibility and error behavior are not covered, keeping it short of a 5.

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?

Two short paragraphs, front-loaded with the action and the fields, followed by the prerequisite and the ID-lookup path. Every sentence carries operational information; nothing is redundant.

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?

An output schema exists, so return values need no explanation, and the description supplies auth requirements, ID sourcing, and partial-update behavior. What remains unstated — failure modes and whether parent/external_id can be cleared — is minor for a four-parameter update tool.

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 coverage is 100% so the baseline is 3, and the description earns more by clarifying the otherwise ambiguous optional-name semantics (current name retained when omitted) and by pointing to list_departments as the source of a valid department_id. It adds genuine meaning beyond the schema's per-field labels.

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 (Update) plus the resource (department) and enumerates the mutable fields (name, parent, external ID). Against siblings create_department / get_department / list_departments, the mutation intent is unmistakable.

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 an explicit prerequisite ('admin only') and routes the agent to list_departments to obtain the required department_id, including the matching strategy (match by name). It does not state when to prefer create_department over an update, but the operational context is otherwise clear.

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

Deploy Server