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?

Annotations already cover non-destructive, idempotent, closed-world, but the description adds the things annotations cannot: the PUSHNOTIF_API_KEY requirement, that saving is free while each live impression costs 1 credit, and the exact JSON shape returned. That is exactly the value-add behavior layer.

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 the sibling exclusion, and every sentence carries information (prerequisite, auth, cost model, return shape). It is dense and somewhat run-on — the trigger/frequency parenthetical could be split — so not 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 10-parameter mutation tool with no output schema, the description supplies the return shape, auth, cost model, idempotency and prerequisite. Gaps are minor: nothing about error behavior (e.g. invalid app_id) or what happens to an already-published banner when inapp_enabled is omitted.

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?

With 100% schema coverage the schema already documents all ten parameters including the trigger and frequency enums, so the baseline is 3. The description does add a little meaning by explaining that inapp_trigger and inapp_freq work together to cap impressions, but most of its parameter prose restates values already in 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 (configure/publish) and resource (In-App Popup or Banner) plus the concrete render styles, and explicitly contrasts it with the OS-notification sibling send_push_notification. An agent can distinguish it from every other tool in the sibling list 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?

Gives both directions: 'use this tool for visual in-page promos and announcements' and 'do not use it for OS lock-screen notifications (use send_push_notification instead)'. It also names a prerequisite (call list_apps first for app_id), which is a routing instruction, not just context.

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 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.

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?

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?

Goes well beyond the annotations by disclosing the PUSHNOTIF_API_KEY requirement, zero credit cost, and the full JSON return shape — valuable since there is no output schema. It does not discuss pagination/truncation behavior for the limit parameter or how totals relate to the returned page, which keeps it from a 5.

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?

Purpose, alternatives, and constraints are front-loaded in the first two sentences, with the return shape last. It is a dense paragraph with some redundancy between the opening enumeration and the trailing return-JSON listing, but every element is functional for an agent without an output schema.

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 auth, cost, filtering, sibling routing, and return structure — everything an agent needs to call a read-only list tool with no output schema. The absence of an output schema is fully compensated by the inline JSON shape description.

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 three parameters are already documented in the schema at a baseline of 3. The description reinforces app_id and tag as narrowing filters but adds no new semantics (e.g., how tag filtering interacts with platform_breakdown counts) and never mentions limit.

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 ('Retrieve active subscriber device records... platform breakdown counts') and enumerates exactly what is returned. It explicitly distinguishes itself from get_campaign_analytics and update_subscriber_tags, so an agent can route correctly 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 positive use cases (inspect audience size, platform distribution, obtain a subscriber_id before update_subscriber_tags) and two explicit exclusions with the alternative tool named for each. When-to-use and when-not-to-use are both covered.

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?

Annotations only declare the generic write/non-idempotent profile; the description adds concrete operational facts: PUSHNOTIF_API_KEY requirement, 1 credit per delivered device with a stated price, zero charge for 404/410 dead tokens that are auto-pruned, and that dispatch is irreversible. It also documents the segment fallback and the url default, which are behavioral, not just schema restatement.

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 action and its scope are front-loaded, and every sentence carries non-redundant information (alternatives, prerequisite, cost, irreversibility, segment/url behavior, return shape). It is a single dense block with several clauses chained into one long sentence, which costs a little scannability but wastes no words.

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?

Despite no output schema, the description enumerates the return fields (ok, campaign_id, total_targeted, total_delivered, total_gone_pruned, credits_deducted, credits_remaining). Combined with prerequisites, cost model, sibling routing, and irreversibility for a non-idempotent destructive-adjacent broadcast, an agent has everything needed to invoke it 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, but the description adds real semantics: segment as 'all' vs a custom tag sourced from update_subscriber_tags with tag-matching delivery behavior, and url defaulting to the app's registered site_url. It doesn't repeat title/body length limits, but those are already fully specified in 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 (broadcast), resource (immediate push notification), delivery channels (VAPID/FCM/APNs), and audience scope (active subscribers of a given app_id). It explicitly distinguishes itself from schedule_push_notification and configure_inapp_banner, so an agent can route correctly 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 explicit when-to-use (instant real-time delivery), explicit when-not-to-use with the two named alternative tools, and a required prerequisite step (call list_apps first to obtain app_id). 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?

Well beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), it discloses the auth requirement (PUSHNOTIF_API_KEY), partial-update behavior (only provided fields change), cost implications (1 credit per welcome push when welcome_enabled=true), the all-or-nothing APNs field group, and the return shape. The only gap is absence of any confirmation of irreversibility or rollback for credential overwrites, which keeps it short of a 5.

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 action and affected fields, then layers usage exclusions, prerequisites, and return contract in a logical order with zero filler sentences. It is dense and long for a single paragraph, but nearly every clause carries operational 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 10 parameters and no output schema, the description compensates by naming the returned JSON keys and stating the prerequisite and credential grouping rules. An agent has everything needed to invoke 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 description coverage is 100%, so per-parameter meaning is already fully documented; the description mainly restates the field set. It does add cross-field semantics the schema cannot express — the APNs four-field coupling and the credit cost tied to welcome_enabled — but that added value is modest against a fully documented schema, so baseline 3 is fair.

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 (update an existing application's branding) and enumerates exactly which fields it touches: icon URL, welcome push copy, and native mobile credentials. It also explicitly delineates from create_app and configure_inapp_banner, so an agent can distinguish it from siblings without opening 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?

Gives positive triggers (configure app-level branding, onboarding welcome alerts, native mobile credentials), explicit exclusions with named alternatives (use create_app instead, use configure_inapp_banner instead), and a prerequisite (call list_apps first to obtain app_id). 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?

The description contributes a lot beyond the annotations: API key requirement, zero credit cost, idempotent tag updates, tag parameters being ignored when unsubscribe=true, and an irreversible token deletion. However, that last point directly conflicts with the annotation destructiveHint=false — an agent trusting the annotations alone would treat this as a safe non-destructive mutation while the description documents permanent deletion. The mismatch undercuts the annotation contract even though the description is the more accurate side.

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 the destructive branch is flagged early, with sibling routing and prerequisites following. It is dense but slightly overstuffed — the redundant '(subscriber_id)' gloss after 'subscriber device' and the trailing return-shape JSON could be tightened without losing 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 the full call envelope for a 4-parameter mutation with no output schema: auth requirement, cost, prerequisite, side effects, parameter precedence, and the return shape { ok, subscriber_id, action, tags, removed }. There is no gap an agent would need to guess at.

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 exceeds it by adding real semantics the schema lacks — that tag updates are idempotent, that add_tags/remove_tags are silently ignored when unsubscribe=true, and that unsubscribe irreversibly deletes the token. Those interactions between parameters are the useful part an agent cannot get from the schema 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?

States a specific verb (assign/remove tags, or unsubscribe) against a specific resource (subscriber device identified by subscriber_id), and explicitly names the sibling it is not (list_subscribers). An agent can distinguish this from every other subscriber-related tool 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 ('manage subscriber segmentation for targeted send_push_notification broadcasts'), explicit when-not ('do not use it to list subscribers, use list_subscribers instead'), plus a stated prerequisite ('call list_subscribers first to obtain a valid subscriber_id'). 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.