Beyond Payday

Update a stock grant

beyondpayday_update_equity_grant

Idempotent

Changes fields on one stock grant. Only the fields provided are changed. Grants are informational: they never change the asset's value or net worth. Beyond Payday works out the figures (before tax) from the vesting schedule: vested_shares, held_shares (vested minus shares no longer held), vested_value (the held shares' value, "Vested, not yet sold"), unvested_shares, unvested_value and next_vest {date, shares}. An ESPP row is a purchase: every share is owned right away. Values are null when no share price is set. An option past its expires_on date has expired: expired is true, its values are 0 and it is left out of the totals. Ask the user for every date, share count and price; never fill one in. Get the id from beyondpayday_list_equity_grants. Figures are estimates from user-entered data — not tax, financial, investment, insurance, or legal advice.

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": {
      "id": "<id>"
    },
    "name": "beyondpayday_update_equity_grant"
  }
}

Input Schema

Name	Required	Description
`id`	Yes
`notes`	No
`expires_on`	No	Options: YYYY-MM-DD they expire.
`grant_date`	No	YYYY-MM-DD the grant was made.
`grant_type`	No	rsu, psu (performance stock units), iso, nso, espp or other.
`vest_start`	No	YYYY-MM-DD vesting starts; falls back to the grant date.
`share_price`	No	What a share is worth now, when the user knows it.
`vest_months`	No	Months the whole grant takes to vest (default 48).
`cliff_months`	No	Months before the first shares vest (default 12).
`strike_price`	No	Options only: the price to buy a share.
`purchase_date`	No	ESPP only: YYYY-MM-DD the shares were bought. Not saved for other kinds.
`double_trigger`	No	RSU or PSU only: true when the shares pay out only after an IPO or a sale of the company, so their vested value is not counted as available yet. Always false for other kinds.
`purchase_price`	No	ESPP only: the price paid per share. Not saved for other kinds.
`shares_granted`	No	Number of shares or options granted.
`vest_every_months`	No	Months between vesting dates: 1 monthly, 3 quarterly, 6, or 12 yearly (default 3).
`expected_updated_at`	No	The record's updated_at from your last read. If given and the record changed since, the update is refused so you can re-read it instead of overwriting someone else's change.
`shares_no_longer_held`	No	Shares sold, withheld for tax or moved to a brokerage (for options: exercised). No more than shares_granted. For ESPP leave it out when shares_granted is already the shares still owned.
`shares_vested_override`	No	When the user knows exactly how many shares have vested; replaces the schedule.

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedOct 7, 2026

addedInput schema / properties / double_trigger

Added value: +{
+  "description": "RSU or PSU only: true when the shares pay out only after an IPO or a sale of the company, so their vested value is not counted as available yet. Always false for other kinds.",
+  "type": "boolean"
+}

changedInput schema / properties / grant_type / description

Previous value: -"rsu, iso, nso, espp or other."New value: +"rsu, psu (performance stock units), iso, nso, espp or other."

changedInput schema / properties / grant_type / enum

Previous value: -[
-  "rsu",
-  "iso",
-  "nso",
-  "espp",
-  "other"
-]New value: +[
+  "rsu",
+  "psu",
+  "iso",
+  "nso",
+  "espp",
+  "other"
+]

addedInput schema / properties / purchase_date

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 10,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "ESPP only: YYYY-MM-DD the shares were bought. Not saved for other kinds."
+}

addedInput schema / properties / purchase_price

Added value: +{
+  "anyOf": [
+    {
+      "maximum": 9999999999,
+      "minimum": 0,
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "ESPP only: the price paid per share. Not saved for other kinds."
+}

addedInput schema / properties / shares_no_longer_held

Added value: +{
+  "anyOf": [
+    {
+      "maximum": 99999999999999,
+      "minimum": 0,
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Shares sold, withheld for tax or moved to a brokerage (for options: exercised). No more than shares_granted. For ESPP leave it out when shares_granted is already the shares still owned."
+}

changedInput schema / properties / vest_every_months / description

Previous value: -"Months between vesting dates: 1 monthly, 3 quarterly, 6, or 12 yearly (default 1)."New value: +"Months between vesting dates: 1 monthly, 3 quarterly, 6, or 12 yearly (default 3)."

AddedOct 5, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Annotations only assert idempotent/non-destructive/closed-world; the description goes well beyond them by disclosing PATCH semantics, derived-field computation from the vesting schedule, expired-option behavior, ESPP purchase treatment, and the expected_updated_at conflict-refusal protocol. It also states that grants never affect asset value or net worth.

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?

The core mutation semantics and id-sourcing instruction are front-loaded, and the text is dense with useful rules. It is long for a single tool, and the enumeration of derived output values plus the advisory disclaimer are somewhat tangential to calling an update.

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?

With 18 parameters, no output schema, and only one required field, the description compensates by explaining the computed values an agent will see, the conflict-detection mechanism, and the input-sourcing obligation. Nothing essential for correct invocation appears 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 coverage is already 89%, so the schema carries most field-level meaning. The description still adds semantic context the schema does not: that ESPP rows are purchases owned immediately, that expired options report zeros and drop out of totals, and that values are null without a share price.

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 ('Changes fields on one stock grant') and immediately defines the PATCH-style scope ('Only the fields provided are changed'), which separates it from create/delete siblings. It does not name a sibling alternative, so it lands just below the top mark.

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 concrete prerequisite for obtaining the id ('Get the id from beyondpayday_list_equity_grants') and a strong data-entry rule ('Ask the user for every date, share count and price; never fill one in'). It offers no explicit when-not-to-use, but the usage context is unambiguous.

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

All Beyond Payday 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?