Payware MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

payware_products_update_placement

DestructiveIdempotent

Replace all details of a product placement by ID; omitted optional fields are cleared, so retrieve current values first and resend those to keep. Placement ID stays unchanged.

Instructions

[Merchant] Replace a placement's details. Every field is replaced, so an omitted optional field is cleared - an omitted campaignId detaches it from its campaign; an omitted active keeps the current value. Get the placement first and send every value you want to keep. The placement ID does not change, so printed codes keep working.

Endpoint: PUT /products/{productId}/placements/{placementId} (PRM plan)

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": {
      "productId": "<productId>",
      "placementId": "<placementId>",
      "name": "<name>",
      "medium": "<medium>",
      "carriers": "<carriers>"
    },
    "name": "payware_products_update_placement"
  }
}

Input Schema

Name	Required	Description
`name`	Yes	Placement name, up to 100 characters, e.g. "Sofia metro posters, October"
`active`	No	Whether it is in use. Governs airing and soundbite attribution; a printed code keeps resolving until the placement is deleted
`medium`	Yes	What the placement is
`channel`	No	Descriptive, e.g. the TV channel or the website, up to 100 characters
`regions`	No	ISO 3166-1 alpha-2 codes of the countries it airs in, matched against the paying bank's country. Empty means anywhere
`activeTo`	No	End of its active window, ISO-8601 with an offset. Empty means the product's
`carriers`	Yes	The methods that carry the placement ID to a payer. SOUNDBITE airs the product's audio and needs airing rules
`location`	No	Descriptive, e.g. the venue or the address, up to 255 characters
`productId`	Yes	The product's ID: pr + 8 letters or digits, e.g. pr7e4rCToG
`activeFrom`	No	Start of its active window, ISO-8601 with an offset. Empty means the product's
`campaignId`	No	The campaign it belongs to, if any (cp + 8 characters)
`useSandbox`	No	Use the sandbox (the default) rather than production
`externalRef`	No	An agency's own code, up to 100 characters
`placementId`	Yes	The placement's ID: pl + 8 letters or digits, e.g. pl7e4rCToG

Schema Changelog

Changes observed during successful MCP inspections.

First observedv2.2.0Nov 10, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds the concrete mechanics behind that: omitted optional fields are cleared, an omitted campaignId detaches the placement from its campaign, and an omitted active keeps the current value. It also reassures that the placement ID is stable so printed codes keep resolving — exactly the non-obvious behavioral detail an agent needs before a destructive replace.

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?

Front-loaded with the verb and resource, then the one caveat that changes caller behavior, then the endpoint and plan requirement. No filler sentences; the parenthetical '(PRM plan)' carries real eligibility information.

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 destructive mutation with no output schema, the description supplies the crucial replace-vs-patch semantics and the read-before-write workflow, and annotations cover safety. It stops short of describing what the response contains or how SOUNDBITE's airing-rule prerequisite interacts with replacement, leaving a small gap.

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 baseline is 3; the description earns more by explaining the semantics that the schema does not: what happens to each omitted field, specifically campaignId (detach) and active (retain). It does not add format or constraint detail beyond the schema, which is already thorough.

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 ('**Replace** a placement's details') and immediately clarifies the full-replacement semantics that distinguish it from an incremental update. Combined with the concrete endpoint (PUT /products/{productId}/placements/{placementId}), an agent can tell exactly what operation this performs versus create/delete/get siblings.

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 explicit operational guidance: 'Get the placement first and send every value you want to keep,' which tells the agent the required read-then-write workflow. It does not name sibling tools or spell out when-not to use it (e.g. versus update_airing/update_audio on the same placement), so it falls short of a full when/when-not/alternative statement.

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

Deploy Server