PushNotif Official MCP Server

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

Beyond the annotations, the description adds authentication requirements (PUSHNOTIF_API_KEY), operational cost context (0 credit cost), and the behavioral difference between passing versus omitting order_id. These details materially help an agent invoke the tool correctly.

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?

The description is dense but front-loaded: purpose, usage routing, operational constraints, parameter behavior, and return shape are all presented without filler. Every sentence contributes to correct tool selection or invocation.

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?

With no output schema, the description compensates by explicitly documenting the JSON return shape, including credits_balance, orders, and recent_ledger. Annotations cover safety behavior, and the single parameter is fully described, leaving no meaningful gap.

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 already 100%, so the baseline would be 3. The description adds practical meaning by explaining that order_id inspects a single invoice, while omitting it lists recent orders and ledger entries.

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 uses a specific verb and resource: checking QRIS top-up order payment status, credit balance, ledger history, and invoice URLs. It clearly distinguishes this tool from create_qris_invoice and get_campaign_analytics, so an agent can identify its scope without opening sibling schemas.

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?

It explicitly states when to use the tool: verifying whether an order from create_qris_invoice has settled or auditing credit consumption. It also names two alternatives and when not to use this tool: creating invoices and viewing campaign analytics.

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

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

Beyond the annotations (readOnly=false, idempotent=true, destructive=false), the description discloses the API-key requirement, the zero-credit cost, and the exact return JSON shape. That is meaningful operational context the agent would otherwise have to guess.

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 primary action, then usage rules, then prerequisites and returns. Dense but every sentence carries actionable information; only the long field enumeration is slightly list-like.

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 7-parameter mutation tool, the description covers purpose, channel routing, auth requirement, cost, and return shape, with annotations already handling the safety profile. Nothing essential to correct invocation is missing.

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 100%, so the schema already documents every parameter. The description names the controlled fields but adds no syntax, format, or default behavior beyond what the schema provides, so it lands at the baseline of 3.

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 and resource ('Configure per-app module switches ... plus sender brand name and Reply-To email address') and enumerates exactly which switches are controlled (OTP, webhook receipts, order status, push). An agent can distinguish it from siblings like send_transactional_email without opening the schema.

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?

Explicitly states the when ('enable or disable individual channels per website') and the when-not with a named alternative ('do not use it to send an immediate email or OTP (use send_transactional_email instead)'). The routing decision is fully specified.

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

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

Goes well beyond the annotations: discloses PUSHNOTIF_API_KEY requirement, the cost model (0 credits to save, 1 credit per live visitor display), idempotent save behavior, and the exact return payload shape. These are non-obvious operational facts an agent cannot get from the structured fields.

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 purpose and sibling exclusion, then prerequisite, cost, and return shape in a logical order with zero filler. It is a single dense block, though, and the trigger/freq parenthetical pushes toward the edge of readability for a 16-parameter tool.

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 16-parameter mutation tool with no output schema, the description covers the prerequisite call, auth key, credit cost, idempotency, and even the return JSON keys. An agent has everything needed to invoke it correctly and predict the response.

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 meaning by explaining the interplay between inapp_trigger and inapp_freq (trigger fires the banner, freq caps repeat impressions) and gives concrete trigger examples like 'scroll_50' and 'event:add_to_cart'. It does not explain segment_tag or the template/image interaction, which the schema carries alone.

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?

Names a specific verb+resource (configure and publish an In-App Popup/Banner) and enumerates the three concrete render modes (center modal, top sticky bar, bottom slide-in toast) plus the rendering mechanism (PushNotif SDK, no browser push permission). It explicitly excludes OS lock-screen notifications and names send_push_notification as the sibling for that case.

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?

States when to use it ('visual in-page promos and announcements'), when not to ('do not use it for OS lock-screen notifications'), the substitute (send_push_notification), and a hard prerequisite ('call list_apps first to obtain app_id'). Nothing key is left to inference.

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

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

Goes well beyond the annotations by disclosing the API key requirement, the credit model (URL generation free, 1 credit per delivered device, toast_only free), and the JSON return keys. The only blemish is the format claim: it says '9 auto-detected formats' but then lists roughly fourteen names, several of which (Mayar, Lynk.id, Duitku, Tripay, Trakteer, Custom JSON) are absent from the platform parameter's enumerated values — a factual inconsistency an agent could trip on.

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 action and the simulate_test branch, then usage, exclusions, prerequisites, cost, and return shape — every sentence carries signal. The verbose parenthetical platform list is the one place where volume exceeds value, especially since it is numerically inconsistent with the schema enum.

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?

No output schema exists, but the description enumerates the response keys, and it covers auth, prerequisites, cost, side effects of the test mode, and sibling routing. Nothing an agent needs to call this correctly is missing.

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 baseline is 3; the description earns an extra point by attaching cost consequences to the mode parameter (toast_only = 0 credits) and by explaining that platform/item_name/buyer_name only matter when simulate_test=true, which the per-parameter schema text does not make explicit.

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+artifact: 'Generate the ready-to-paste Universal Incoming Webhook URL (POST /api/v1/apps/{app_id}/incoming-event)' plus the alternative branch when simulate_test=true. An agent can distinguish this from configure_rss_autopush and send_push_notification without opening any schema.

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?

Explicitly names the use cases (payment gateway, Supabase, tipping page, e-commerce) and the exclusions with named alternatives ('do not use it for RSS blog feeds (use configure_rss_autopush instead) or manual push campaigns (use send_push_notification instead)'). It also states the prerequisite ('call list_apps first to obtain app_id').

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, openWorldHint=true, so the description's added context is the differentiator: SSRF URL validation, GUID/URL deduplication so each post is sent once, the PUSHNOTIF_API_KEY requirement, and a per-subscriber credit cost of 1 per broadcast. It falls just short of 5 because it does not state what happens to an existing configuration when parameters are omitted (partial update vs reset).

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-loads the core action and the immediate-dispatch variant before routing, prerequisites, and cost. The middle sentence is dense with nested parentheticals and stacked clauses, which is efficient but slightly harder to scan than a cleanly split structure.

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 mutating multi-mode configuration tool with open-world network behavior, the description covers prerequisites, auth, validation, deduplication, billing impact, mode precedence, and even the return shape ({ ok, app_id, rss_enabled, ... }) despite no output schema. Nothing an agent needs in order to call it correctly is missing.

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 baseline is 3; the description still adds genuine meaning by clarifying that dispatch_now fetches and broadcasts 'even if rss_enabled=false', a precedence rule absent from the schema's property text. It also reinforces that rss_feed_url is required when enabling polling or dispensing, but adds no interval-duration or prefix-format detail beyond the schema.

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 and resource ('Configure automated 24/7 RSS, Atom, or XML Sitemap polling for an app_id') and adds the alternate mode ('trigger an immediate feed check and push broadcast via dispatch_now=true'). It also names the two siblings it is not (send_push_notification, schedule_push_notification), so an agent can discriminate it without opening a schema.

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?

Gives an explicit positive trigger ('when a blog, news portal, or store wants newly published URLs automatically broadcast') plus two explicit exclusions that name the correct alternative tool for each. It also states a prerequisite sequence ('call list_apps first to obtain app_id'), leaving nothing to inference.

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

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

Beyond the annotations (which already cover idempotency and non-destructiveness), the description discloses the auth requirement (PUSHNOTIF_API_KEY), the credit cost (0), and the critical side-effect constraint that it does not overwrite the In-App Promo Banner. It also returns the response shape, all of which annotations alone cannot convey.

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?

The core purpose and the sibling exclusion are front-loaded, and every sentence carries information (auth, cost, return shape). The opening is a long, dense sentence with a nested parenthetical that could be split for readability, keeping it just short of a 5.

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 12-parameter mutation tool with no output schema, the description covers auth, cost, non-destructive scoping relative to the banner, and the JSON return shape. There is no meaningful gap an agent would need to guess at before calling 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 coverage is 100%, so the baseline would be 3; the description adds slight value by framing the three 'automated DOM/webhook sensors' that map to the sensor params and by enumerating the returned fields. It doesn't restate enums or defaults, but it doesn't need to given the rich schema.

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 (Configure) plus the exact resource (standalone Live Activity Social Proof Toast) and its three sensors, and even parenthesizes what the toast actually is. It explicitly separates itself from configure_inapp_banner, so an agent can distinguish it from siblings without opening any schema.

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?

Gives explicit when-to-use cases (enable/disable toasts, change theme or corner, toggle auto-capture sensors) and an explicit when-not with a named alternative ('do not use it for promo popups (use configure_inapp_banner instead)'). Nothing is left to inference.

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

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

Annotations only declare the safety profile (non-read-only, non-destructive, non-idempotent), and the description adds the information that actually matters for calling it: PUSHNOTIF_API_KEY is required, the operation costs 0 credits, and it creates a persistent record. It also discloses the generated artifacts (ECDSA P-256 VAPID keypair, SDK snippet), which cannot be inferred from annotations.

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?

It is dense but front-loaded: the purpose sentence comes first, then usage routing, then constraints and return shape, in that order. Every sentence carries distinct information and none repeats the name or annotations.

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 non-idempotent mutation tool with no output schema, the description supplies auth requirements, cost, persistence, input validation rules, and the exact return JSON shape. An agent has everything needed to call it correctly and interpret the result.

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 schema already documents both parameters, including the HTTPS/localhost constraint and the 2–80 character name limit. The description's restatement of the site_url origin rule adds little beyond the schema, so the baseline 3 applies.

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 precise verb and resource ('Register a new website domain or mobile application') plus the concrete side effects (VAPID keypair, HTML SDK snippet). It explicitly names the siblings it is not (update_app_branding, delete_app), so an agent can separate it from every adjacent tool.

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?

Gives the positive trigger ('when adding an additional website or app to an existing account') and two explicit exclusions with the correct alternatives for each. Nothing about tool selection is left to inference.

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

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

Goes well beyond the annotations: discloses the required PUSHNOTIF_API_KEY, that the order is PENDING and expires in 30 minutes at zero fee, that crediting happens automatically on webhook confirmation (i.e. the call does not itself deliver credits), and the amount_rp-vs-package_id precedence. This is the mutation lifecycle detail an agent needs and cannot get from readOnlyHint/destructiveHint alone.

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?

Dense but front-loaded: purpose first, then exclusion, then auth/lifecycle, then parameter conflict, then return shape. Every clause carries information, though the inline JSON return shape makes the sentence long and slightly heavy to parse.

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?

With no output schema, the description usefully spells out the returned JSON fields including qris_checkout_url and expires_at. The remaining hole is behavior with zero arguments, since both parameters are optional and the description never says which one is defaulted to.

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, and the description adds the flat Rp 0.20/credit rate, the Rp 1,000 minimum, and the precedence rule in prose. It does not state what happens when neither optional parameter is supplied (required params = 0), which is the one semantic gap.

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 and resource ('Create a prepaid credit top-up invoice') plus the payment rail (Indonesian QRIS, all banks and e-wallets), which makes it trivially distinguishable from billing/status siblings. An agent knows exactly what is being created without opening the schema.

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?

Explicitly names the trigger ('when the user wants to purchase additional credits') and the anti-trigger with the exact alternative tool ('do not use it to check whether an existing invoice has been paid (use check_billing_and_qris_status instead)'). No inference required.

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

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

Annotations already declare destructiveHint=true and confirm_delete is in the schema, but the description adds real context the annotations cannot: the cascade deletion scope, the API key requirement, the zero credit cost, and that the call is rejected without confirm_delete=true. Only missing the return format, which prevents a 5. It does not contradict the idempotentHint=true annotation, since a repeat delete would leave the same end 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?

Four sentences, no redundancy: purpose and cascade first, then usage boundary, then prerequisite and cost/auth, then return shape. Each sentence carries distinct, actionable information.

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?

Covers authentication, cost, cascade scope, confirmation safety, and return keys, which is thorough for a two-parameter destructive tool with no output schema. The description could not have done much more without becoming verbose.

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 100%, so both parameters are already documented. The description restates confirm_delete behavior and app_id provenance from list_apps but adds no syntax or format detail beyond what the schema provides, meeting the baseline.

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 (permanently delete) and resource (registered application) plus the exact cascade of what is removed: subscriber device tokens, scheduled campaigns, delivery history. The scope alone distinguishes it from update_app_branding and configure_inapp_banner, which it names explicitly.

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?

Gives an explicit when-to-use condition (user asks to remove a duplicate or decommissioned app) and an explicit when-not-to-use condition (pausing notifications or changing app settings), naming the two alternative tools. It also states a prerequisite: call list_apps first to verify app_id and subscriber count.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety bar is covered; the description goes well beyond that by disclosing the required PUSHNOTIF_API_KEY credential, the 0-credit cost, and the aggregation semantics when app_id is omitted. These are operationally relevant facts an agent could not derive from structured fields.

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?

Content is ordered well: purpose, metric scope, usage and exclusions, auth/cost, then return shape, so it is front-loaded with what matters most. The single dense paragraph and the full JSON return sketch could be tightened, but every clause carries useful information.

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?

With no output schema, the description takes on the burden of describing returns and does so fully (summary totals plus campaign and scheduled_queue item shapes). For a two-parameter read-only tool this covers everything an agent needs to call it and interpret results correctly.

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 parameters are already documented and baseline is 3. The description adds meaning beyond the schema by explaining the consequence of omitting app_id (aggregation across all workspace apps bounded by limit rows), which clarifies intent rather than repeating format details.

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 (retrieve) and specific resources (push campaign delivery metrics and scheduled queue items), enumerating the exact metric fields and the cmp_sch_xxxx ID format. It also explicitly names the siblings it is not (check_billing_and_qris_status, list_subscribers), so an agent can distinguish it without opening another schema.

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?

Gives concrete when-to-use cases (audit campaign performance, look up scheduled campaign IDs before editing/canceling) and names the follow-on tool schedule_push_notification. It also states explicit when-not cases with the correct alternatives for QRIS invoices and subscriber device lists, leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds material context not in them: the PUSHNOTIF_API_KEY requirement, the zero-credit cost, and the conditional side effect of include_sdk_framework injecting SDK snippets per app. It also states the exact return payload, which matters since no output schema exists.

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 dense paragraph, front-loaded with the purpose and then prerequisites, exclusions, and return shape in priority order. No filler sentences, though the inline JSON return signature makes it heavier to read than ideal; a short bullet structure would scan faster.

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 two-param, no-output-schema read tool, everything an agent needs is present: auth requirement, cost, prerequisite ordering, alternative for device-level inspection, optional parameter behavior, and the response shape. Nothing material is left to inference.

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 enumerating and explaining the effect of include_sdk_framework values ('html', 'nextjs', 'laravel', 'wordpress', 'flutter') — each app entry gains ready-to-paste setup code. It says nothing about the app_id filter parameter, leaving that entirely to the schema.

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?

Opens with a precise verb+resource+scope: 'List all registered websites and mobile apps in the workspace' including subscriber counts and credit balance. It explicitly distinguishes itself from list_subscribers and names the write tools it feeds, so an agent can place it correctly among 15 siblings without opening a schema.

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?

Gives an explicit prerequisite rule ('use this tool first ... before calling send_push_notification, schedule_push_notification, update_app_branding, delete_app, configure_inapp_banner, configure_rss_autopush') and an explicit exclusion ('do not use it to inspect individual subscriber devices (use list_subscribers instead)'). Both when-to-use and when-not-to-use, with named alternatives, are stated.

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

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

The annotations already establish readOnly, idempotent, non-destructive, and closed-world behavior. The description adds useful context beyond annotations: it requires PUSHNOTIF_API_KEY, has 0 credit cost, supports zero-downtime migration export, and describes the return payload shape.

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?

The description is dense but front-loaded: purpose, usage, exclusions, requirements, and return shape all appear in a single efficient paragraph. Every sentence contributes to selection or invocation.

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?

There is no output schema, but the description compensates by naming the returned JSON fields and explaining export behavior. Given the annotations and complete parameter schema, an agent has enough information to call the tool correctly.

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. The description adds semantic value for export_format by explaining the full VAPID endpoint/p256dh/auth migration dump, and it clarifies app_id and tag filtering, though limit is left entirely to the schema.

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 uses a specific verb and resource (retrieve active subscriber device records) and clearly covers the platform breakdown and export modes. It also distinguishes the tool from get_campaign_analytics and update_subscriber_tags, so an agent can select it without opening sibling schemas.

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?

It gives explicit use cases: inspect audience size, see platform distribution, export subscriber tokens, or obtain a subscriber_id before calling update_subscriber_tags. It also states when not to use it, naming both get_campaign_analytics for campaign metrics and update_subscriber_tags for modification/import.

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

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

Beyond the annotations (readOnlyHint false, idempotent true, destructive false), it discloses cost (0 credits), a brute-force rate limit, the conditional mutation behavior ('read-only unless new_name or new_password is supplied'), and the exact response envelope. This resolves the ambiguity inherent in a tool whose readOnlyHint is false despite being primarily a login.

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?

It is front-loaded with the primary action and scope, then alternatives, then operational facts. Dense but every clause carries information; the response-shape clause is arguably the least essential given no output schema exists, but it is still useful and compact.

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 4-parameter login-and-profile-update tool with no output schema, the description covers preconditions, cost, rate limiting, conditional mutation, alternatives, and the return JSON shape. Nothing an agent needs to call it correctly is missing.

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 schema already documents all four parameters. The description adds value by framing new_name and new_password as optional inline profile updates triggered on login and tying them to the 'profile_updated' return value, which the schema alone does not convey. It does not restate length constraints, which is fine since the schema covers them.

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 names a specific verb (authenticate), resource (existing PushNotif account), and the concrete outcome (retrieve live API key and registered apps, with optional profile update). It also explicitly contrasts with register_new_account and update_app_branding, so an agent can route between siblings without opening any schema.

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?

It states exactly when to use this tool (existing users connecting from chat, or updating credentials) and when not to, naming the correct alternatives for signups and app-level branding. The prerequisites ('requires valid email and password, no prior API key needed') are also spelled out.

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

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

Beyond the annotations, the description discloses the rate limit (5 OTPs per 10 min per IP), OTP validity window, that step 2 irreversibly creates a tenant plus an ECDSA P-256 VAPID keypair, and that the endpoint is public with no API key. These are behavioral facts the structured fields do not carry.

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?

The two-step mechanism and sibling exclusions are front-loaded, and every clause carries operational information. It is dense to the point of being a single long sentence, which slightly hurts scannability, but nothing is 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?

A non-idempotent, open-world mutation tool with no output schema is fully covered: the description supplies the return payload shape (ok, step, tenant, app fields including the API key and VAPID key), the rate limit, and the irreversibility warning. An agent has everything needed to call it correctly and interpret the response.

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; the description earns above that by explaining the conditional coupling of otp_code with password and name and by tying each parameter set to a step. It does not add format constraints beyond what the schema already states (length minimums, HTTPS origin).

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 states a concrete verb and resource (register a new account via OTP) and spells out the two-step protocol explicitly. It names the sibling tools it is not (login_existing_account, create_app), so an agent can distinguish it from all 15 siblings without opening a schema.

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 when-to-use ('only for brand-new user signups') and when-not-to-use rules with named alternatives for each case. The two-step invocation condition (omit otp_code first, pass it on the second call) is stated as a routing rule, not left to inference.

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

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

Goes well beyond the annotations: discloses the PUSHNOTIF_API_KEY requirement, the credit model (0 up front, 1 credit per delivered device charged when the schedule fires), and the mutual exclusivity of cancel/update/create modes, plus the return shape. Minor gap: annotations declare destructiveHint=false while the description says cancel_campaign_id will 'delete' and 'remove from the queue' — the description could reconcile that asymmetry (irreversible queue removal vs. no data destruction) rather than leave it implicit.

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 verb+resource and every sentence carries information (alternatives, prerequisites, auth, cost, mode exclusivity, return shape). Dense single-paragraph packing of mode rules and cost rules makes it slower to scan than a short bulleted breakdown would be.

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 an 8-parameter, zero-required mutation tool with conditional requirements and no output schema, the description supplies the mode logic, prerequisites, credential/cost behavior, and an inline return shape — everything needed to call it correctly in any of its three modes.

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 per-parameter meaning is already documented; the description still adds value by explaining that the three mode parameters are mutually exclusive and that passing neither means create. It does not, however, explain interactions such as what happens if title/body are supplied with cancel_campaign_id, or how scheduled_for and recurrence_rule interact.

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?

Names specific verbs and a specific resource: creating, editing (via update_campaign_id) and cancelling (via cancel_campaign_id) scheduled/recurring push campaigns, and explicitly excludes two named siblings (send_push_notification for immediate sends, configure_rss_autopush for feed polling). An agent can distinguish this from every sibling without opening the schema.

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 when-to-use ('delayed, recurring, or editable future broadcasts'), when-not ('do not use it for immediate sending'), and named alternatives for the excluded cases. It also gives the prerequisite chain (call list_apps for app_id; call get_campaign_analytics for cmp_sch_xxxx), which is exactly the guidance an agent needs before invoking.

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

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

The annotations already indicate a non-read-only, non-idempotent, open-world operation, and the description adds substantial behavioral context beyond them: required PUSHNOTIF_API_KEY, credit cost per delivered device with dead-token exceptions, irreversibility after dispatch, and segment-specific delivery behavior. There is no contradiction with the annotations.

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?

The purpose and exclusions are front-loaded, and the description is dense with useful operational details. However, it is a long single paragraph that could be easier to scan if broken into shorter sentences or sections.

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 complex, irreversible mutation tool with billing and authentication implications, the description covers prerequisites, costs, side effects, segment behavior, defaults, and the return payload fields. Since no output schema exists, including the JSON return shape is especially valuable.

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 100%, so all six parameters are already documented in the schema. The description reinforces a few semantic details, such as segment filtering and the url default, but mostly repeats information already present in the parameter descriptions rather than adding significant new meaning.

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 states a specific verb and resource: broadcast an immediate push notification across Web Push, Android, and iOS to active subscribers of a specific app_id. It clearly distinguishes itself from schedule_push_notification and configure_inapp_banner, so an agent can identify its purpose without opening the schema.

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?

It explicitly says when to use this tool (instant real-time delivery) and when not to use it, naming the alternatives for future/recurring broadcasts and on-site HTML popups. It also includes the prerequisite to call list_apps first to obtain app_id.

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

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

Beyond annotations, the description discloses API key requirements, credit costs for sending versus verifying OTP, the prohibition on bulk use, and the return shape (JSON delivery receipt or verification token). These details materially help an agent understand side effects and constraints.

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?

The description is front-loaded with the core action and stays dense with relevant details. It is slightly long due to parenthetical examples and cost details but every sentence carries useful information.

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 tool with no output schema, the description covers purpose, action modes, cost model, API key requirement, restrictions, and return values. An agent has enough context to invoke it correctly without needing more explanation.

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 100%, so the baseline is 3. The description adds meaningful semantic context by linking action=verify_otp to zero credits and other actions to 25 credits, which helps an agent choose the right action mode.

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 states a specific verb and resource: send transactional email or verify OTP. It explicitly distinguishes 1-to-1 transactional use from bulk marketing blasts, so an agent can identify the correct tool and avoid sibling tools like send_push_notification.

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?

It gives clear usage context: transactional 1-to-1 emails and managed OTP verification, with an explicit prohibition on bulk marketing. It does not name alternative sibling tools for related operations, so it falls short of a 5.

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

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

Annotations already declare non-read-only, idempotent, non-destructive behavior, but the description adds important operational context: PUSHNOTIF_API_KEY is required, only provided fields are updated, welcome pushes can deduct credits, and APNs fields must be supplied together. These details materially help an agent invoke the tool safely.

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?

The description is dense but front-loads the update action and then layers use cases, exclusions, prerequisites, operational notes, and return shape. It could be split for readability, but every section adds useful routing or behavioral information.

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 14-parameter mutation tool with no output schema, the description is unusually complete: it covers purpose, exclusions, prerequisites, authentication, cost behavior, field dependencies, and even the return JSON keys.

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 100%, so the schema already documents all 14 parameters thoroughly. The description adds some grouping and reinforces the APNs field dependency, but most parameter semantics are already covered by the schema.

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 states a specific verb and resource: update an existing application's notification icon, welcome push, VAPID keys, and mobile credentials. It clearly distinguishes this tool from create_app and configure_inapp_banner, so an agent can route correctly.

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?

It explicitly lists when to use the tool: app-level branding, onboarding welcome alerts, custom VAPID migration, and native mobile credentials. It also names alternatives for excluded cases and states the prerequisite to call list_apps for app_id.

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

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

The description adds substantial context beyond the annotations: required PUSHNOTIF_API_KEY, zero credit cost, the returned JSON shape, and the fact that unsubscribe is permanent and deletes the device record. However, that permanent-delete disclosure directly conflicts with the annotation destructiveHint=false — an agent trusting the hint could invoke a destructive branch without seeking confirmation. The content is otherwise rich, but the conflict makes the safety profile unreliable.

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?

The three operating modes are front-loaded in a single dense but well-ordered sentence, followed by usage routing, prerequisites, and return shape. Every clause carries information, though the density of mode/cost/auth/return details in one paragraph makes it slower to scan than a bulleted structure would be.

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 7-parameter, output-schema-less tool with multiple modes, the description supplies the mode routing, the auth requirement, the cost, and the return fields ({ ok, subscriber_id, action, tags, removed, imported, updated }). Nothing essential for a correct call is missing.

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 orchestration semantics the schema does not: it explains that subscriber_id applies to tag/unsubscribe modes while import_app_id combines with import_csv or import_subscribers for bulk import, i.e. which parameter combinations form valid modes. That is meaningful beyond the per-field descriptions.

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 names the resource (subscriber device, keyed by subscriber_id) and enumerates the three distinct operations it performs: tag add/remove, permanent unsubscribe, and bulk CSV/JSON import. It also explicitly distinguishes itself from list_subscribers, so an agent can route correctly without opening the sibling schema.

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?

It gives an explicit when-to-use list ('manage subscriber segmentation, remove a device, or migrate subscribers from OneSignal/LaraPush/Webpushr') and an explicit when-not-to-use with the named alternative ('do not use it to list or export subscribers (use list_subscribers instead)'). The mode-selection conditions (unsubscribe=true, import_app_id + import_csv or import_subscribers) are stated inline.

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