configure_payment_webhook

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

Goes well beyond the annotations by disclosing auth requirements (PUSHNOTIF_API_KEY), the exact cost model (URL generation 0 credits, 1 credit per delivered device for live/simulated broadcasts, toast_only 0 credits), and the response envelope. This is important because annotations mark the tool non-read-only and idempotent but say nothing about side effects or billing.

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?

Front-loaded with the core action and endpoint, then usage, exclusions, prerequisites, costs, and return shape in a logical order. It is dense — the opening sentence carries an eight-item platform list and two modes — but nearly every clause adds decision-relevant information, with little redundancy.

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?

For a six-parameter mutation tool with a simulated-write path, the description covers everything an agent needs: prerequisite resolution of app_id, auth, cost implications per mode, exclusions to sibling tools, and the returned JSON keys (which substitute for the absent output schema). Nothing material is left unspecified.

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 coverage is 100%, so the baseline is 3, but the description adds real value by tying credit cost to the mode parameter (toast_only costs 0 credits) and by restating app_id's provenance from list_apps. It does not, however, explain how platform and simulate_test interact in the description beyond the schema's own wording.

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?

States a specific verb+resource ("Generate the ready-to-paste Automated Payment & Order Webhook URL") with the exact endpoint path, and lists both operating modes (URL generation vs. simulate_test=true firing a live event). It also names the eight supported platforms, so the agent knows precisely what it produces and for whom.

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?

Explicit affirmative case ("Use this tool when connecting a payment gateway or e-commerce store...") plus two named exclusions routing to siblings: configure_rss_autopush for feeds and send_push_notification for manual campaigns. It also states the prerequisite, call list_apps first to obtain app_id, which prevents the most likely invocation error.

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