Payments Ops MCP

Overview Schema Source Related Servers Discussions Admin

propose_contract_terms

Idempotent

Validates PSP contract terms against source quotes, flags blocking errors and changes, and stages a proposal for human confirmation before saving.

Instructions

Validate contract terms extracted from a PSP contract or pricing schedule and stage them for confirmation.

Nothing is saved yet. Call save_contract_terms after the person confirms.

Args: psp_name: Payment provider name, e.g. "AcmePay". effective_from: Date the terms start, YYYY-MM-DD. card_fee_percent: Percentage fee as a percent, e.g. 2.9 for 2.9% (not 0.029). card_fee_fixed: Fixed fee per transaction in major units, e.g. 0.30. payout_delay_days: Days from capture to payout (e.g. 2 for T+2). currency: ISO currency code of the fees. international_surcharge_percent: Extra percent for international cards, if any. chargeback_fee: Fee per chargeback in major units, if any. reserve_percent: Rolling reserve percent, if any. sources: For each field above, the exact clause text it came from, copied verbatim. document_text: Full text of the contract, so each quote can be checked.

Returns each term with a source check (verified / quote_not_found / number_not_in_quote / no_source), errors that block saving, warnings, changes versus the terms currently on file, and a proposal_id.

Input Schema

Name	Required	Default
`sources`	No
`currency`	No	USD
`psp_name`	Yes
`document_text`	No
`card_fee_fixed`	Yes
`chargeback_fee`	No
`effective_from`	Yes
`reserve_percent`	No
`card_fee_percent`	Yes
`payout_delay_days`	Yes
`international_surcharge_percent`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Nov 4, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Adds real behavior beyond the annotations: that this mutates only staged state (proposal_id returned), that validation can produce blocking errors vs warnings, and that a diff against currently-on-file terms is produced. Annotations declare non-read-only, idempotent, non-destructive, and the description is consistent with that while clarifying the staging semantics. Minor gap: no mention of auth requirements or what happens to a prior unconfirmed proposal.

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?

Front-loaded with purpose and the saving gate before the Args list, and the Args block is justified given zero schema coverage. The Returns sentence is somewhat redundant with the existing output schema and could be trimmed slightly.

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 an 11-parameter, 5-required validation tool, the description covers purpose, staging semantics, units, quote-provenance requirements, and failure modes. With an output schema present, the brief return summary is more than sufficient.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must carry the full burden, and it does: it documents all 11 parameters, including unit conventions ("2.9 for 2.9% (not 0.029)"), major-unit fixed fees, T+N payout semantics, ISO currency, and the verbatim-quote requirement for sources. This prevents the most likely invocation errors.

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+resource ("Validate contract terms extracted from a PSP contract or pricing schedule") plus a stage step ("stage them for confirmation"). This clearly separates it from the sibling save_contract_terms, which the description explicitly names.

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

Usage Guidelines5/5

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

Gives an explicit sequencing rule: "Nothing is saved yet. Call save_contract_terms after the person confirms." The agent knows both when to use this tool and which tool follows it, plus the human-confirmation gate.

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

Deploy Server