SwiftProbate

create_heir

Add a new heir to the estate. Use when the user wants to record a person who may inherit (spouse, child, stepchild, grandchild, parent, sibling, or other relative). Call once the customer has confirmed how the person is related to the DECEASED — any wording is accepted. "My brother Tom" is the customer's brother, not the deceased's: ask (e.g. "Is Tom your mom's son?") before saving.

Input Schema

Name	Required	Description
`name`	Yes	The heir's name exactly as the customer gave it. Never add a last name or any part they didn't give — ask for the full name if a form needs it.
`email`	No	Email address
`notes`	No	Free-text notes about this heir — context like whereabouts unknown, predeceased details, per-stirpes notes, disputes, or anything the user wants remembered. Multi-line OK.
`phone`	No	Phone number (any format)
`address`	No	Mailing address (free text, multi-line OK). Used for formal probate notice.
`is_minor`	No	Whether the heir is under 18. Required for every living heir except a spouse or parent — if the user hasn't said, ask them; never assume an adult.
`estate_id`	Yes	The estate to act on. Call list_my_estates first to get this id.
`is_deceased`	No	Whether the heir is deceased (default false). Used for per stirpes inheritance.
`is_divorced`	No	For a spouse only: whether they are a divorced/former spouse (default false). A divorced spouse is recorded for a complete family picture but is not a surviving spouse and does not inherit under intestacy.
`relationship`	Yes	Relationship to the deceased. Canonical values: spouse, child, stepchild, grandchild, parent, sibling, other. If the user's wording doesn't match one (e.g. 'half-brother', 'daughter-in-law', 'adult stepchild'), pass their wording as-is — it is normalized automatically. Never re-ask the user for a 'valid' relationship.
`parent_heir_id`	No	ID of the parent heir if this person inherits through a deceased parent (e.g. grandchild whose parent predeceased the decedent). Omit otherwise.
`name_from_document`	No	true when the name was read from a document the customer shared rather than typed by them.
`relationship_detail`	No	The relationship exactly as the user described it, when it carries more than the canonical value (e.g. 'stepson', 'half-sister', 'goddaughter'). Shown on probate forms, so preserve the user's words.
`relationship_confirmed`	No	true only when the customer has said or confirmed this person's relationship to the deceased (not to themselves), in this conversation or in a document they shared.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedNov 1, 2026

changedInput schema / properties / name / description

Previous value: -"Full legal name of the heir"New value: +"The heir's name exactly as the customer gave it. Never add a last name or any part they didn't give — ask for the full name if a form needs it."

addedInput schema / properties / name_from_document

Added value: +{
+  "description": "true when the name was read from a document the customer shared rather than typed by them.",
+  "type": "boolean"
+}

addedInput schema / properties / relationship_confirmed

Added value: +{
+  "description": "true only when the customer has said or confirmed this person's relationship to the deceased (not to themselves), in this conversation or in a document they shared.",
+  "type": "boolean"
+}

Changed1 schema field changedOct 16, 2026

changedInput schema / properties / is_minor / description

Previous value: -"Whether the heir is under 18 (default false)"New value: +"Whether the heir is under 18. Required for every living heir except a spouse or parent — if the user hasn't said, ask them; never assume an adult."

First observedOct 11, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare a non-idempotent, non-destructive write, so the safety profile is covered. The description adds real behavioral context beyond that: a confirmation gate before saving, automatic normalization of non-canonical relationship wording, and integrity rules (never append a last name, never assume an adult). It omits what happens on duplicate heirs or what the call returns.

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?

Purpose is front-loaded in the first sentence, then prerequisites, then the ambiguity trap. Three sentences, no filler, and the long final sentence is entirely the disambiguation rule that prevents the most likely data-entry error.

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?

For a 14-parameter mutation with no output schema, the description covers the decision gates that matter: who qualifies, confirmation of relationship, and how to record it. It leaves out duplicate handling and any note on the returned heir record, which an agent might reasonably want before calling.

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. The description still earns credit above baseline by adding policy the schema does not carry: the relationship must be confirmed against the deceased, ambiguous first-person phrasing must be re-asked with the given example, and any wording is accepted without re-prompting.

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 and resource — 'Add a new heir to the estate' — and scopes it by enumerating who counts as an heir (spouse, child, stepchild, grandchild, parent, sibling, other relative). This clearly separates it from update_heir (modifying an existing record) and get_heirs (reading), so the agent can pick it without opening either schema.

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 a clear trigger ('Use when the user wants to record a person who may inherit') plus a hard precondition ('Call once the customer has confirmed how the person is related to the DECEASED'). It does not name the sibling alternatives (update_heir, mark_heirs_complete) or state when not to use it, so it stops short of full when/when-not routing.

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

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