marketplace_get_payment_link

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful scoping fact that the link targets an installed location, but says nothing about link lifetime, single-use behavior, or whether the returned link creates any server-side state.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, no filler, and the distinguishing scope ('for an installed location') is front-loaded. Nothing wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Five required parameters, 20% schema coverage, no output schema, no annotations explaining return shape, and no usage guidance — yet the description is a single clause. An agent still would not know what the link is for, when it expires, or how discount affects it.

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

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

Schema description coverage is only 20% (just partner_id), and the description adds zero parameter meaning for application_id, location_id, tariff_option_id, or discount, all required. The semantics of 'discount' (percent 0-100 per schema) are never connected to the generated link.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb+resource ('Generate an Altegio-hosted Marketplace payment link') and scopes it to 'an installed location', which separates it from sibling write-payment tools like marketplace_record_payment and marketplace_refund_payment. Minor friction: the tool name says 'get_' while the description says 'Generate'.

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

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

There is no indication of when to call this versus adjacent tools (record_payment, refund_payment) or what precondition must hold beyond the implicit 'installed location'. No exclusions, no sequencing, no mention of when the link should be discarded.

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