Fictura

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

Goes well beyond the readOnly/destructive annotations: explains that SANDBOX environments mean test purchases underpin the verdict, that cancellation only flips will_renew while access persists to expires_at, and that unknown users return 'none' instead of erroring. This is exactly the non-obvious behavior an agent needs.

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 verdict definition, then packs three valuable caveats into one dense sentence. No filler, though the multi-clause sentence is 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 still surfaces the key response fields (environment, will_renew, expires_at) and the unknown-user case, so the agent knows what to expect. It doesn't enumerate the full return shape, but it covers what matters for correct use.

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?

Only one parameter (`user_id`) with 100% schema coverage, so the schema already documents it as a device, account, or RevenueCat id. The description says 'one user' but adds no format or resolution detail beyond the schema — baseline 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 — 'authoritative paid/not-paid verdict for one user' — and names the unified backends plus the REST endpoint it mirrors. An agent can immediately distinguish it from get_user or get_analytics 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 concrete decision guidance: always inspect `environment` before granting production access, and treats unknown users as a valid 'none' rather than an error. It doesn't name a sibling as an alternative, so it falls just 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false), it adds two genuinely useful facts: the flow is never made live here, and it requires an MCP key with edit permission. It omits what happens on name collision or whether the document is validated, but the safety/auth profile is well covered.

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?

Two tight sentences with zero filler, and the key constraint (draft only, never live) is front-loaded. Nothing is repeated from the annotations or 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?

For a create mutation with no output schema and a free-form nested object, the description covers permissions and lifecycle but leaves the agent guessing about the return value (draft identifier?), validation of the supplied doc, and duplicate-name behavior. Adequate but with clear gaps.

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 pointing to get_onboarding_doc's reference for the free-form `doc` object, which the schema only describes as "A complete onboarding document" with additionalProperties {}. That pointer gives the agent real guidance on what to put in the opaque nested parameter.

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 ("Creates a draft onboarding flow") plus its source ("from a document you wrote") and explicitly marks the artifact as non-live. It is distinguishable from create_paywall_draft and get_onboarding_doc, though the boundary with save_onboarding_doc is left implicit.

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?

The description clarifies that going live happens in the dashboard, which implies this tool's scope stops at draft creation, and it points to get_onboarding_doc for reference. However, it never says when to choose this over save_onboarding_doc or validate_onboarding_doc, so the routing guidance is only implied.

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 readOnlyHint=false and destructiveHint=false, so the description is not carrying the safety burden alone. It adds real context beyond them: the created object is always a draft and publishing happens in the dashboard, and an MCP key with edit permission is required — both are behaviors an agent can't infer from 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?

Two sentences, front-loaded with the core action, then the draft-only boundary and auth requirement. No filler; the parenthetical about list_templates is dense but directly useful for calling the 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 mutation tool with no output schema and a nested doc object, the description covers the key risks: it never publishes, requires an edit-capable key, and where template_key comes from. Minor gap: no indication of what is returned on success (e.g., a paywall/draft identifier) or how the nested doc is validated.

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, but the description adds provenance the schema lacks: template_key must come from list_templates and specifically the webview templates, and doc is the alternative to a template rather than a complement. It leaves the mutual exclusivity of template_key and doc implied rather than stated.

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 ('Creates a draft paywall') and distinguishes the two creation sources: a Studio template key or a supplied document. It also routes to the sibling list_templates for keys, which helps separate it from read/update tools, though it never explicitly contrasts itself with save_paywall_doc or validate_paywall_doc.

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 is never made live: going live is done in the dashboard' clearly sets the scope boundary and tells the agent not to look for a publish path here. 'from list_templates — the webview ones' gives concrete guidance for obtaining template_key, but no explicit when-not or comparison against the update/validate siblings.

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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: output reflects unsaved live state (not persisted data) and includes a document model reference. It does not say what happens with a stale or invalid pairing_id, 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?

Two sentences, the payload description is front-loaded and the sequencing rule follows. The first sentence is a long comma-chained list, but every element is informative and none is filler.

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 carries the burden of explaining return values, and it does so thoroughly: document content, paywall identity, current screen, selected node, and model reference. An agent knows both what it receives and how to act on 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?

There is a single parameter with 100% schema description coverage ('From pair_editor'), so the schema already carries the semantics and baseline 3 applies. The description never mentions pairing_id or its dependency on pair_editor, so it adds nothing here.

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 resource and states precisely what is read: the live document including unsaved changes, the paywall, the active screen, the selected node, and the model reference. It implicitly distinguishes itself from the stored-document sibling (read_doc) by emphasizing 'exactly as it is on the person's screen,' though it never names that sibling 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?

It gives an explicit sequencing rule — 'Read this before editor_set_doc' — plus a working instruction ('edit what you got — keep node ids, change only what was asked'). That tells the agent both when to call this tool and how its output feeds the follow-up call.

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 destructiveHint/readOnlyHint annotations, the description adds real context: the change is not saved, the person can undo it and saves manually, and the document is validated first and refused with problems. It also notes the auth requirement ('Needs an MCP key that can edit'), which annotations do not cover.

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?

Three short sentences, each earning its place: the action, the persistence/undo behavior, and validation/auth. The most decision-relevant facts (NOT saved) are front-loaded and capitalized.

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 nested-object mutation with no output schema, the description covers validation failure, non-persistence, and auth prerequisites well. Minor gaps remain around the note parameter and the return value on refusal, but nothing critical 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 coverage is 100%, so the schema already documents doc, note, and pairing_id. The description reinforces that doc is validated and complete but adds no syntax or format detail for the note or pairing_id parameters beyond the schema. 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?

The description gives a specific verb+resource ('Replaces the document in the person's open editor') and distinguishes this from the get/read/save siblings by scoping it to the live editor canvas. An agent can route between editor_set_doc, editor_get_doc, and save_onboarding_doc 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?

The description makes clear this is for pushing a document into the person's open session rather than persisting it, and it says the change is visible and undoable. It stops short of explicitly naming alternatives like save_* or validate_* and when to prefer them.

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 establish that this is a read-only, non-destructive, closed-world operation. The description adds useful behavioral context by noting that `roas` includes blended totals and explicitly-unattributed revenue, and it warns the agent to keep attributed and blended figures separate when reporting.

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 compact and front-loads the view distinctions, with each sentence mapping to a specific view. It is efficient, though it starts with view names rather than an explicit overall purpose sentence, which the title supplies instead.

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 read-only, multi-view reporting tool with full schema coverage and annotations, the description is largely complete. Since there is no output schema, the view-by-view explanation of returned metrics is especially valuable; the main gap is the lack of routing guidance against similar sibling analytics tools.

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 `view`, `days`, `since`, `until`, and `provider`, including their view-specific applicability. The description explains what each view returns but does not add syntax, defaults, or other meaning beyond the schema's parameter documentation.

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 clearly enumerates the three view outputs: `roas` for per-campaign spend, attributed users, revenue, CPI, CAC and ROAS; `spend` for raw daily ad-spend rows; and `links` for tracking links. It is specific about the resource being retrieved, though it does not explicitly distinguish this tool from sibling analytics/attribution tools such as `get_attribution_report` or `get_analytics`.

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?

The view descriptions imply when to choose each view: `roas` for campaign performance metrics, `spend` for raw daily ad-spend rows, and `links` for tracking links. However, it gives no explicit when-not guidance or comparison to sibling tools that also report attribution or analytics data.

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 readOnlyHint=true and destructiveHint=false, so the safety burden is lower. The description adds useful behavioral context beyond annotations, including the ~100-user sample-size caveat and the last-28-days window for `stores`.

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 and compact, with each sentence adding useful information: view definitions, sample-size caveat, and store-specific scoping. There is little or no filler.

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 one-parameter read-only tool with no output schema, the description is largely complete because it summarizes the return content for every view. It does not specify default date ranges for `overview`, `funnel`, or `cohorts`, nor does it describe response shape or pagination.

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, but the description earns above that by explaining what each of the four `view` enum values actually returns. It turns the enum into actionable semantics rather than just repeating `Which analytics view to return`.

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 analytics resource and clearly enumerates the four views, so the agent knows what the tool does. It does not explicitly distinguish this tool from sibling analytics tools, especially get_store_analytics, which overlaps with the `stores` view.

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?

The description explains what each view returns, so choosing among the four enum values is implied. However, it never states when to use this tool instead of sibling tools such as get_store_analytics or get_acquisition_report, and gives no explicit when-not guidance.

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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaningful context beyond that: the SDK key is publishable, safe to commit, and identifies the app rather than a person — useful disclosure for handling the returned credentials.

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?

Three tight sentences, front-loaded with what is returned, followed by the imperative usage rule and the security caveat. No filler; each sentence adds distinct value.

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 explicitly enumerates the three return values, so the agent knows what to expect. Combined with the pre-code-generation directive and the key-safety note, nothing essential is missing for correct invocation.

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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies no input is needed, and there are no parameter semantics to mis-specify.

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 specific values returned — API base URL, the app's publishable SDK key (gk_…), and the RevenueCat webhook URL — so the agent knows exactly what resource is being fetched. It is clearly distinct from status/report siblings like get_setup_status or get_analytics.

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, emphatic when-to-use rule: 'ALWAYS call this before generating integration code — never leave a placeholder API key.' That is a strong usage directive, but it does not distinguish this tool from the similarly named get_setup_status sibling, leaving a small routing ambiguity.

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 readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious semantics: imported verdicts never overwrite Fictura's own SDK-resolved attribution, and filtering is on install date rather than event date. No mention of result size limits or pagination, hence not 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?

Three sentences, front-loaded with the returned content, then a behavioral caveat, then the alternative. The opening clause ('What the AppsFlyer import brought in about where people came from') is slightly wordy but still earns its place by framing the data as imported attribution.

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 carries the burden of describing results, and it does name the breakdown dimensions (source, acquisition vs retargeting, top campaigns). Missing detail on whether figures are user counts versus other metrics and on any result-size cap keeps it below 5.

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 since/until/top_campaigns are already documented with formats, bounds and default. The description only adds that the date filter applies to install date and that top campaigns are part of the output, which is marginal over 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 precisely what is returned: imported attributions of people, split by media source (organic included), by acquisition vs retargeting, plus top campaigns. The 'imported AppsFlyer' scoping and the named breakdowns distinguish it cleanly from get_attribution_report and get_acquisition_report 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 an explicit alternative for a different question ('For revenue and ROAS by source, use get_attribution_report with view=kpis'), including the exact parameter value. It doesn't explicitly exclude the other attribution/acquisition siblings, but the routing guidance for the main ambiguity is concrete.

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 establish that this is a read-only, non-destructive, non-open-world tool. The description adds useful behavioral detail by enumerating the status fields returned, including progress, skipped duplicates, people created, date range, and error 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?

The description is only two sentences and contains no filler. The first sentence is a dense enumeration, but each listed return field is relevant to a status 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?

With no output schema, the description carries the burden of explaining return values and does so thoroughly: connection state, latest run status, progress, row counts, duplicates, people created, date range, and errors. It also gives the key usage precondition.

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?

The tool takes zero parameters and schema coverage is 100%, so there are no parameter semantics for the description to clarify. Baseline 4 is appropriate.

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 exactly what this tool reports: AppsFlyer connection state, the latest import run details, and whether any import has ever finished. It is clearly a status/read tool and is distinguished from the sibling start_appsflyer_import.

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 usage context: call this before start_appsflyer_import to avoid offering a finished import again. That names the related sibling and the condition for calling this tool, though it does not spell out when not to use it.

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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful context in the form of default windowing (trailing 28 days) and what each view contains, but says nothing about pagination behavior for installs, result caps, or latency for large windows.

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 a plain-English purpose statement, then a tight enumeration of the three views, then the default window. Nearly every sentence earns its place, with only the opening aphorism being slightly decorative.

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 five-parameter read-only reporting tool with no output schema, the description covers what each view returns and the default date range, which is what an agent needs to pick a view. Minor gaps remain around result size and breakdown interactions, but nothing critical 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 all five parameters, their enums, and defaults are already documented in the schema. The description reinforces the view semantics and the default window, but adds no syntax or format detail beyond what the schema states — the baseline of 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?

The description names a specific reporting resource and enumerates the three views (summary, kpis, installs), each with the data it exposes. It is clear what the tool retrieves, though it never distinguishes itself from siblings like get_acquisition_report or get_appsflyer_attribution_summary.

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?

Usage is implied through the view breakdown — an agent can infer that kpis is for per-source breakdowns and installs for row-level data — and the trailing-28-day default sets context. There is no explicit when-to-use guidance, no exclusions, and no routing advice toward the acquisition or Appsflyer siblings.

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?

With annotations already declaring this a safe read-only operation, the description adds substantial behavioral detail about the return payload: 50 recent occurrences, stack traces, release/environment, 30 days of counts, and source-map-resolved fields. It also tells the agent to read stack_resolved/frames instead of the minified stack, which is valuable behavioral guidance.

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 return contents, then explains when to use it, then adds the source-map and trace caveats. The three sentences are dense but every one adds useful operational detail.

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, so the description carries the burden of explaining what is returned. It does so thoroughly, including occurrence count, stack fields, source-map resolution, daily counts, and how to continue with get_trace, leaving little ambiguity for correct invocation.

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?

The single issue_id parameter has 100% schema description coverage and is documented as coming from list_error_issues. The description adds no further parameter semantics beyond what the schema already provides, so the baseline of 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?

The description clearly states that this retrieves one error issue in full, including the group, recent occurrences with stack traces, release/environment, and daily counts. It distinguishes the tool as the one for fixing production errors, though it does not explicitly contrast with get_error_issue_brief or list/search_error_issues.

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 a clear primary use case: 'when asked to fix a production error.' It also tells the agent to use get_trace for occurrences with a trace_id, but does not discuss when to prefer the brief/list/search variants.

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 readOnlyHint and non-destructive, so the safety profile is covered. The description usefully adds behavior beyond that: stack frames are resolved when source maps exist, and the output is an aggregation (stack + frames + breadcrumbs + facets + cause chain + prompt). It says nothing about response size, latency, or what happens when data is unavailable.

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?

A single front-loaded sentence that labels the result type first ('One issue condensed for fixing it') and then itemizes the payload. Every clause carries content; nothing is filler.

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 carries the burden of explaining returns, and it does so by enumerating the sections of the brief. Minor gaps: no mention of failure behavior for an invalid or missing issue, and no differentiation from the plain get_error_issue tool.

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% and the schema already tells the agent the issue_id comes from list_error_issues. The description adds no parameter detail whatsoever, 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?

The description names a specific resource and operation: one issue condensed with a fix prompt, and it enumerates exactly what the brief contains. It doesn't, however, distinguish itself from sibling get_error_issue, so an agent can't tell the two apart from this text alone.

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?

'Condensed for fixing it' implies the use case (you want to act on an issue, not browse), but there is no explicit when-to-use or when-not guidance and no mention of get_error_issue or search_error_issues as alternatives. Usage is inferable but not 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds useful return-content context, namely that variants and full Bayesian results are included, which is not in the annotations. It does not cover not-found behavior or other operational details, but the bar is lower with 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 definition is a single front-loaded fragment with no filler. It is appropriately sized for a simple one-parameter lookup, though its terseness is also the source of the usage-guidance gap.

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 simple one-parameter read tool with no output schema, the description gives enough return-value orientation ('variants and full Bayesian results') and the annotations cover safety. It is not fully complete because it omits failure behavior and explicit when-to-use guidance.

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?

The single parameter has 100% schema coverage and is documented as 'Experiment id, from list_experiments'. The description adds no additional parameter semantics beyond the schema baseline, so 3 is appropriate.

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 identifies the resource and singular scope ('One experiment') and states what it returns ('variants and full Bayesian results'). It is clear that this is the single-experiment counterpart to list_experiments, though it does not explicitly name the sibling or use a verb.

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?

The description gives no explicit instruction on when to use this tool versus list_experiments or other experiment tools. The only hint is the id parameter's schema note 'from list_experiments', leaving the retrieve-by-id use case to be inferred.

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 readOnlyHint=true and destructiveHint=false, but the description adds the non-obvious failure mode: misconfigured app_links causes BOTH association files to fail silently with no error and links falling back to the browser. That is exactly the kind of behavioral context annotations 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?

Front-loaded and dense — the per-view breakdown follows immediately and every clause carries information. The silent-failure warning is slightly verbose relative to a one-parameter read tool, but it is the highest-value content in the description, so it largely earns its space.

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 read-only, single-enum, no-output-schema tool, the description covers what each view returns and the critical verification step. It does not touch on response shape beyond the app_links fields or any auth/scope requirements, but little 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% and the single enum is already documented, so the baseline is 3. The description goes beyond that by explaining what each enum value actually yields (app_links → association file contents; domains → branded domains plus DNS verification state; web_config → smart banner; esp → email provider link setup), which meaningfully disambiguates the choice.

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 resource (deep link / tracking domain configuration) and then enumerates exactly what each of the four views returns — team id, bundle id, package, SHA-256 fingerprints, ready flags, DNS verification state. An agent knows precisely what this tool surfaces and how it differs from config siblings like get_app_setup or get_push_config.

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 steers usage per view ('app_links is the most important for integration work') and gives a concrete operating instruction — verify the ready flags rather than assuming. It stops short of naming when to prefer a sibling tool (e.g., get_setup_status) or when this tool is the wrong choice, so it earns a 4 rather than 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the shape of the payload (document, status, version, model reference) and by warning that the round-trip with save_onboarding_doc must preserve step keys and node ids. It does not state permissions scope or whether the returned document is a snapshot vs. live, which is why it is not 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?

The payload description is front-loaded and the editing guidance follows immediately; every clause carries information. The opening construction ('The JSON document ... is made of') is slightly convoluted, and the edit guidance could be one clause tighter, but there is no filler.

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 carries the return-value burden and does so adequately for a single-parameter read: it names the document, its status, its version, and the model reference. The edit-in-place constraint on the round trip with save_onboarding_doc is the key behavioral fact an agent needs. Missing only error/empty cases (e.g. what happens for an unpublished or missing flow).

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% and the single `id` parameter is fully documented, including its provenance ('from list_surfaces'). The description adds no further meaning about the id. Baseline 3 applies when the schema does the heavy lifting.

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 concretely identifies the resource — the JSON document behind a builder-made onboarding flow — and enumerates what comes with it (status, version, document-model reference). Naming 'onboarding flow' also implicitly separates it from the paywall analog, though it never names get_paywall_doc/editor_get_doc explicitly. It is a noun phrase rather than a verb+resource, which costs a little crispness.

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 a clear prerequisite ('Read this before save_onboarding_doc') and an operating rule ('edit the document you got rather than writing one from scratch — keep step keys and node ids, change only what was asked'). That is real when-to-use guidance. It stops short of naming exclusions, e.g. when editor_get_doc or validate_onboarding_doc should be preferred instead.

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 readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds value by disclosing the returned package (document body + status + version + model reference) and an important content rule about price variables. It does not state whether the returned document is a snapshot or live-editable reference, which is the one behavioral question left open.

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?

Three sentences, front-loaded with the return payload before the workflow advice and the price-variable caveat. The pricing note is slightly tangential for a pure read tool but directly supports the intended read-then-edit loop, so it earns its place.

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 must characterize the return value, and it does so by naming the document, its status/version, and the model reference. Combined with the strong annotations and full schema coverage, an agent has enough to call and interpret it, though the exact response envelope shape remains implicit.

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% and the single id parameter is already documented with its provenance ('from list_surfaces'), so the baseline of 3 applies. The description adds no further detail on the identifier or its format.

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 the specific resource (the JSON document of a Studio paywall) and enumerates what it carries: status, version, and a reference to the document model. It does not explicitly contrast with near siblings like read_doc, editor_get_doc, or get_surface, so an agent must infer which of several doc/surface readers returns the editable paywall document.

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 a concrete workflow rule: read this before save_paywall_doc and edit the retrieved document rather than authoring one from scratch. It also gives an in-place editing constraint (keep node ids, change only what was asked). What it lacks is disambiguation from read_doc/editor_get_doc, which likely return similar shapes.

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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description still adds real value beyond them: it discloses that output is aggregated per billing cohort and explicitly guarantees no device tokens or individual recipients are returned, which matters for a privacy-sensitive read.

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?

A single front-loaded sentence delivers the purpose, the exact breakdown of returned counts, and the privacy boundary, with no filler. Every clause earns its place.

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 must carry the return-value burden, and it does reasonably: cohort breakdown and the OneSignal flag are named. It stops short of describing the response shape (field names, nesting, zero-device case), but the essential contract is clear.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the schema being empty means no semantic gap exists.

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 resource and what is returned: registered-device counts broken out by billing cohort and whether OneSignal is configured. The resource is distinct enough from siblings like get_setup_status or get_app_setup that confusion is unlikely, but it never explicitly routes against those overlapping 'is it set up' tools.

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?

Usage is only implied — an agent infers you call this when you need to know if push is configured or how many devices are registered. There is no explicit when-to-use, no exclusion, and no mention of the nearest alternative (get_setup_status / get_app_setup).

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 the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description earns credit by adding a non-obvious behavioral trait: a disabled feature is a server-side kill switch that the SDK obeys, so the answer has runtime consequences. It does not, however, describe response format or whether integration status is cached or live, which matters since there is no output schema.

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?

Two sentences, front-loaded with what is returned and then why it matters, with no filler. The first sentence is long and list-like ('Stripe, RevenueCat, Slack, Sentry, App Store Connect, …') but every item earns its place by signaling the breadth of integration coverage.

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 carries the burden of indicating return content, and it does by enumerating the three sections the caller will get. The ellipsis after the integration list leaves the exact set of providers unspecified, and it never touches on how the setup checklist is structured or whether the payload is large.

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?

The tool takes zero parameters, so there is no parameter semantics to document; the baseline for a no-param tool is 4. Nothing in the description misleads about inputs.

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 resource — the app's configured state — and enumerates its three components (setup checklist, feature toggles, third-party integrations) with named examples. It is clear what the tool returns, though it never distinguishes itself from the similarly named sibling get_app_setup or from check_entitlement.

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?

'Use it to check whether a feature is enabled before writing code that depends on it' gives a concrete trigger condition for invoking the tool. It stops short of naming an alternative (e.g., get_app_setup, check_entitlement) or when not to call it, so the routing among overlapping siblings 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 already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds real behavior on top: the data origin is an Appfigures sync, monetary values are in micros of `currency`, the revenue figure must not be combined with RevenueCat revenue, and the not-configured failure mode is disclosed. Those are exactly the details an agent cannot get from the annotations or schema.

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 payload contents, then adds the two constraints that prevent misuse, in three compact sentences with no filler. The dense enumeration is informative rather than redundant, since no output schema exists to convey the returned fields.

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, so the description must convey the return surface — and it does, enumerating every metric family plus the `connected: false` case. With both parameters fully documented in the schema and annotations covering safety, 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 description coverage is 100%, with both `days` and `reviews` documented including defaults and bounds, so the schema carries the parameter burden. The description adds no parameter-level guidance (e.g., how lookback affects the ratings snapshot or review counts), so the baseline of 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?

The description enumerates exactly what the tool returns (downloads, re-downloads, updates, uninstalls, store revenue, top countries, ratings snapshot, reviews, chart positions), which is a specific resource scope rather than a restatement of the name. It also separates itself from the RevenueCat-based analytics siblings by stating that store revenue is a distinct figure from RevenueCat revenue.

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?

The description gives clear operative context: these are store-reported (not RevenueCat) numbers, the two revenue figures must never be summed, and a `connected: false` signal indicates Appfigures is not configured. It stops short of an explicit 'use this instead of get_analytics when...' routing statement or any exclusion, so it stops at 4.

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 establish that this is a safe read-only, non-destructive, closed-world operation. The description adds genuinely useful domain behavior: configs do not contain price strings and prices resolve at render time from PurchasesAdapter packages, warning the agent not to copy price literals.

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 two sentences and front-loads the core purpose. The second sentence is a focused, high-value caveat about price literals rather than filler.

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 read-only retrieval tool with fully documented parameters and safe-operation annotations, the description covers purpose and the key price-handling caveat. It does not detail the shape of version history or error behavior, but no output schema exists and the missing details are not required to invoke 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%, with the id and kind parameters fully documented in the schema, including the enum for kind and the note that id comes from list_surfaces. The description adds only the broad implication that exactly one paywall or onboarding flow is retrieved, so baseline 3 is appropriate.

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 retrieval action and resource: the full configuration of one paywall or onboarding flow plus version history. It is clear enough to distinguish from generic list/search tools, though it does not explicitly contrast with sibling doc-oriented tools such as get_paywall_doc or get_onboarding_doc.

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?

The phrase 'full configuration ... plus its version history' implies when this tool is useful, but there is no explicit when-to-use/when-not-to-use guidance or named alternative. The schema description points to list_surfaces for the id, but the tool description itself does not route the agent among siblings.

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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value by describing the return shape (a span tree with named fields) and the attached error events, which the annotations cannot convey. It stops short of mentioning limits, truncation on very large traces, or span-count caps, so not 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?

Two sentences, both front-loaded: the first defines the payload, the second gives id acquisition and intent. No filler, no repetition of the title, and the dense field enumeration is warranted for a tool with no 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?

With no output schema, the description carries the burden of explaining return values and does so thoroughly (tree structure, span fields, error events). Combined with 100% schema coverage on the only input parameter and full annotation coverage of the safety profile, an agent has everything needed to call 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% and already documents the single trace_id parameter as a 32-character hex W3C trace id, so the baseline is 3. The description adds provenance beyond the schema by saying the id should be taken from a get_error_issue occurrence, which changes how the agent acquires the value.

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 ('get' a 'distributed trace') and enumerates the returned content: every span as a tree with names, services, start offsets, durations, HTTP status, errors, plus linked error events. This is clearly distinguishable from sibling get_error_issue, which is referenced as the id source rather than a substitute.

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 tells the agent where the required argument comes from ('Take the trace_id from an occurrence in get_error_issue') and states the two use cases ('see where the time went or what failed first'). That is when-to-use guidance plus a concrete routing rule to the sibling tool, not just implied 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds the useful disclosure that the result set is unbounded-in-principle ('every event this app has ever sent') and flags the capture-switched-off field, but says nothing about pagination, truncation, or result size for what could be a very large catalog.

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?

Two sentences, no filler. The return contents come first, the usage guidance and its rationale second, which is the right ordering for an agent deciding whether to call it.

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 correctly spends its words describing what comes back and why it matters. The only shortfall is the absence of any note on volume, pagination, or whether capture-disabled events are included by default versus filterable.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the schema is empty and coverage is 100%. Baseline 4 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 precisely what the resource is (every event the app has sent) and what each row carries: volume, last-seen, and capture-disabled status. No sibling tool covers event instrumentation, and an agent can immediately tell this is the event catalog read rather than an analytics or experiment query.

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 trigger — call this before adding instrumentation — plus the reason (avoid near-duplicate event names) and a downstream consequence (the name mirrors the experiment's primary metric string). That is a genuine when-to-use, and no alternative tool exists to route away from.

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=true, destructive=false and closed-world, so safety is covered. The description adds real behavioral context beyond that: results are stitched across devices/accounts/RevenueCat ids, and the payload includes event breakdown, churn state and recent activity. It omits edge behavior such as not-found handling or any activity-window limits.

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?

Two sentences, zero waste: the payload contents are front-loaded and the accepted identifier forms follow. Every clause carries information an agent can act on.

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 a single fully documented parameter, a read-only annotation profile and no output schema, the description carries the needed burden by summarizing the return payload. The remaining gap is edge-case behavior — what is returned when the identifier resolves to nothing or to multiple identities.

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% and the parameter description already says 'Master user id, or any known identifier'. The description adds only the concrete identifier types (device id, account id, RevenueCat id), which is a modest but genuine extension over the schema, so it sits at the baseline rather than above it.

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 precisely (a single user) and enumerates exactly what comes back: stitched identity across device/account/RevenueCat ids, event breakdown, churn state and recent activity. It does not explicitly contrast with the sibling list_users, but the 'one user's ... full history' framing makes the single-entity scope unmistakable.

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?

Usage is implied: fetch a full profile for one known user, versus the list_users sibling. There is no explicit when-to-use/when-not statement and no mention of what to do if the user is unknown or ambiguous across identities. The identifier flexibility is guidance about input, not about tool selection.

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 the safety profile (readOnly, non-destructive), so the description's real value is the behavioral detail it adds: a missing provider connection returns a not_connected result rather than erroring, and the call goes out to the provider's live API. That failure-mode disclosure is exactly the kind of info annotations cannot convey. It doesn't cover latency, rate limits, or partial-provider failures.

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?

Three short sentences, front-loaded with what the tool returns, then the failure behavior, then the routing hint. Every sentence carries distinct information — nothing restates the name or the 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?

No output schema exists, so the description must sketch the return shape, and it does: status, daily budget, ad sets, plus the not_connected sentinel result. With one enumerated parameter and a clear read-only annotation set, this is nearly all an agent needs. A little more on what an ad-set object contains or pagination would push it to 5.

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?

There is a single required parameter with full schema description coverage and a seven-value enum, so the schema fully documents 'provider'. The description adds nothing about provider selection or what happens with the 'test' enum value. Baseline 3 is appropriate when the schema carries the parameter semantics 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?

The description names a specific resource and the fields returned (status, daily budget, ad sets), and combines with the title 'List live ad campaigns' to make the verb and scope unambiguous. It falls just short of a 5 because the opening clause is elliptical — 'Campaigns read live from a connected ad platform' — rather than stating the action outright.

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 routes the agent away from this tool for a specific case: 'prefer get_acquisition_report for historical numbers.' That is a named alternative with the condition that selects it. It does not state when-not to call it for any other reason (e.g., missing provider auth beyond the graceful not_connected path), so it stops short of full when/when-not coverage.

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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine context by disclosing the return content (28-day funnel metrics and tracking links), but says nothing about volume, pagination, or whether all creators are returned unfiltered.

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?

A single dense sentence that front-loads the resource and then enumerates the returned metrics. Every clause carries information; there is no filler.

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 must carry the return-value burden and does so reasonably, specifying the funnel stages and links included. It falls slightly short on result volume/ordering and on confirming no filtering is possible, which matter for a list tool returning per-creator aggregates.

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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify. The only thing not stated is that the 28-day window is fixed and non-configurable, which is a minor omission for a no-arg tool.

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 (creator records) and precisely enumerates the payload: a 28-day funnel per creator plus tagged tracking links. The 'list' action is carried by the name/title rather than the description, and it does not distinguish itself from nearby list_* or get_attribution_report siblings, so it stops short of a 5.

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

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

There is no statement of when to reach for this tool versus siblings such as list_users, get_attribution_report, or get_analytics, and no prerequisites or exclusions are given. The agent must infer usage entirely from the resource name.

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 readOnlyHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the return structure (paths grouped by section, one-line descriptions) and the auth situation ("No API key required"). It does not discuss index size or response limits, so it stops 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?

Two short sentences, front-loaded with what the tool returns followed by when to use it. Every clause carries information and 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?

There is no output schema, so the description must explain return values, and it does (paths, sections, one-line descriptions). The main missing piece is any note about index size or truncation, but for a zero-parameter read tool the definition is otherwise complete.

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?

The tool takes zero parameters, so the baseline of 4 applies. There is no parameter semantics to explain, and the description correctly does not invent any.

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 clearly that it returns the full documentation index: every page path grouped by section with a one-line description. This is specific about content and a reader can tell it apart from search_docs and read_doc. It does not name those siblings explicitly, so it falls short of a 5.

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?

"Use it to find the right page when a search term is hard to guess" gives a concrete condition for choosing this over search_docs, which is implied rather than named. There is no explicit when-not guidance, but the context is clear enough.

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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real context beyond that: the default scope (unresolved only) and the meaning of the `synthetic: true` marker (SDK-captured console lines, not crashes), which is a genuine semantic distinction an agent would otherwise misread. It stops short of noting result limits or pagination.

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?

Three short sentences, front-loaded with the most useful information (what the feed contains) before the default-scope and synthetic caveats. No filler, though the opening is a noun phrase rather than an action statement, which slightly weakens the lead.

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 carries the burden of describing returns and does so well — counts, sparkline window, uptime summary. For a two-optional-param read tool that is largely sufficient, though it omits any mention of ordering, result caps, or what the grouping keys are.

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, and the description's 'defaults to unresolved' merely restates the schema default. The `synthetic: true` explanation is about a response field, not an input parameter, so it does not add parameter-level meaning; `include_legacy` and the notion of 'grouping v2' are left entirely to the schema's one-line note.

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 identifies the resource (grouped error issues) and enumerates exactly what comes back — level, status, event/user counts, a 14-day sparkline, uptime summary — which is more informative than the name alone. However it never names a verb and never distinguishes itself from the sibling search_error_issues or get_error_issue_brief, so an agent must infer the split.

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 the default behavior ('Defaults to unresolved issues only'), which implies this is the unfiltered feed listing, but it never says when to reach for it instead of search_error_issues or get_error_issue. No exclusions, no prerequisites, no guidance on which status value to pick.

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 the safety profile (readOnly, non-destructive, closed-world), and the description adds real context beyond them: results are conditional on status, with full Bayesian detail only for running or finished experiments. It omits volume/ordering concerns for a list-everything tool, 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?

A single front-loaded sentence with no filler; the conditional qualifier ('for running or finished ones') is placed before the payload list so the reader knows the results are partial for other statuses.

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 carries the return-value burden and does name the key fields (exposures, conversions, probability-best variant). Gaps remain: no mention of scope boundaries (all experiments in the account? by surface?), ordering, or whether the call is expensive for large accounts.

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?

The tool takes zero parameters, so there is no parameter semantics to document; the baseline of 4 applies. The description correctly spends no words on inputs and instead covers scope of output.

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 resource (every experiment) and what comes back with it (status plus Bayesian results for running/finished ones). The verb is only implied by the name, and it never explicitly names get_experiment as the single-item alternative, so sibling differentiation is left to inference.

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?

Usage is only implied: the 'every experiment' framing suggests bulk retrieval versus the singular get_experiment sibling, but there is no explicit when-to-use statement, no exclusions (drafts? archived?), and no guidance on choosing between this and get_experiment.

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 the read-only, non-destructive, closed-world safety profile, and the description adds real context beyond them: that price points are scoped per subscription by Apple, so the call's output shape changes when subscription_id is passed. It doesn't mention pagination or result limits, which keeps it off 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?

Three short sentences, front-loaded with the resource and its fields, then the use case, then the conditional parameter behavior. No filler, and each sentence carries distinct 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 compensates by naming the returned fields and explaining that the payload changes when subscription_id is supplied. Nothing about pagination or error cases is covered, but for a two-parameter read tool this is close to complete.

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, but the description goes further by explaining the purpose of subscription_id (fetch Apple's price ladder for that one product) and the underlying constraint that price points are per-subscription. The territory parameter's role is left entirely to the schema, which is acceptable at full coverage.

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 resource (this app's auto-renewable subscriptions in App Store Connect) and enumerates the returned fields (product id, billing period, Apple review state), which pins down the tool precisely. The verb is only implied by the field listing rather than stated up front, and no sibling is named, keeping it just below a 5.

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?

"Use it to check that a paywall references a product that actually exists" gives a concrete triggering scenario. The second half explains the conditional behavior of subscription_id and why there is no global price-point listing, though it doesn't contrast against a named alternative tool.

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 a safe read, so the description instead spends its space on non-obvious behavior: the resolution precedence (running experiment > live > none) and the silent-failure mode where a nonexistent placement 'renders nothing at all, with no error'. It also discloses how the list is built (configured ∪ observed), which is exactly the kind of context annotations cannot 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?

Three sentences, front-loaded with what is returned and then escalating to the 'IMPORTANT' warning. The precedence notation ('running experiment > live > none') compresses a rule that would otherwise need a paragraph. Nothing is padding.

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 must describe return values, and it does: surfaces, per-placement serving state, and the valid placement names. It stops short of saying what identifying fields accompany each paywall/onboarding entry (ids, status) that an agent would need to chain into `get_paywall_doc` or `get_onboarding_doc`, leaving a small 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?

The tool takes zero parameters, so there is no parameter semantics to document and the baseline of 4 applies. The description uses the space instead to characterize the output fields (`placements`, `observed`) that would-be parameters relate to.

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-and-resource pair ('Every paywall and onboarding flow' plus the placement list) and states what the tool resolves per placement ('running experiment > live > none'). It is clearly distinguishable from the singular sibling `get_surface` and from draft-creation tools.

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 instruction: read `placements` before writing a placement string into code. That is a clear trigger condition. It does not name sibling alternatives (e.g. `get_surface` for a single surface), so it falls short of a full when/when-not/alternatives statement.

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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds value beyond that by disclosing what the call yields — the template key and a sense of what each template looks like — which matters since there is no output schema.

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?

Two sentences, zero waste, with the resource and scope front-loaded and the usage cue following. Every clause earns its place.

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 single-parameter read tool with no output schema, the description covers the resource, the trigger, and the shape of the return. Only minor gaps remain, such as whether the catalog is paginated or fixed.

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% and the single `kind` parameter has an enum with its own description, so the schema does the heavy lifting. The description's mention of 'paywalls or onboarding flows' loosely reinforces the two enum values but adds no format or selection detail beyond 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 first sentence names the specific resource (built-in one-click starter templates) and its two scopes (paywalls, onboarding flows) plus what is returned (template key and appearance). It is clearly distinguishable from siblings like get_paywall_doc or create_paywall_draft, though the phrasing is a noun phrase rather than a verb+resource statement.

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 a concrete trigger: 'Use this when asked to add a paywall so you pick a real template key rather than inventing one.' That routes the agent correctly and explains the motivation. It stops short of naming explicit alternatives or exclusions, so it is clear context rather than full when/when-not guidance.

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 the safety profile (readOnlyHint, non-destructive, closed-world), and the description adds genuinely useful behavior beyond them: the sort order, the exact fields returned, and — most importantly — that results are capped and `total` reports the pre-cap match count. The one gap is that it never says how to page past the cap, which matters for a tool whose whole purpose is listing many records.

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?

Two tight sentences, front-loaded with the resource and ordering, followed by the return shape and the cap caveat. The nine-state parenthetical is long but earns its place by mapping directly to the enum an agent will pass.

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 only two optional parameters, no output schema, and full annotation coverage, the description does nearly all the work an agent needs: what comes back, in what order, and that results are truncated. The remaining shortfall is the absence of any pagination or 'how to see more' note alongside the cap.

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 both `limit` (max 200, default 50) and `churn_state` are fully documented in the schema, and the description's enumeration of states simply restates the schema enum. The description contributes no extra semantics such as whether filtering happens before or after the limit is applied — which would be genuinely valuable here.

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 clearly identifies the resource (the app's users) and its ordering (most recently active first), plus the fields returned and the churn state derivation. It stops short of explicitly distinguishing itself from the sibling get_user, so the reader must infer that this is the bulk-list version rather than the single-record fetch.

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

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

There is no explicit statement of when to call this versus get_user, list_creators, or a report tool. The churn-state enumeration hints at a filtering workflow, but that guidance lives in the schema, not the description, and no alternatives or exclusions are named.

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 (which only say non-readonly, non-destructive, closed-world) by disclosing that the code is single-use and expires in 10 minutes and that a pairing lasts 24 hours or until either side stops it. This is exactly the operational context an agent needs to avoid stale-pairing failures.

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?

Three sentences, front-loaded with the action and then the return value and lifetime constraints. No filler and every clause carries information the agent needs.

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 only one parameter and no output schema, the description supplies the return value (pairing_id), its consumer (editor_* tools), and both expiry windows. Nothing material for 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 coverage is 100% and already documents the string bounds, but the description adds real meaning: the code is 6 characters and is found under 'Pair an agent' in the Studio UI, telling the agent what to ask the user for. Minor tension with the schema's 4-12 length range is not explained.

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 ('Connects to the paywall editor a person has open') and identifies the exact input (the 6-character pairing code in Studio). It is clearly distinguishable from siblings like unpair_editor and the editor_* tools it unlocks.

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?

Implies the usage context well by stating it returns a pairing_id 'for the editor_* tools', telling the agent this must precede editor operations. It does not explicitly state when not to call it (e.g. already paired — use unpair_editor first) or name the alternative.

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 establish readOnlyHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description still adds genuine context beyond them: full markdown is returned, no API key is needed, and a bad path returns nearest-path suggestions rather than failing silently.

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?

Three short sentences, front-loaded with the return value, then the input format, then the error path. No sentence is redundant and nothing is buried.

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 and only one parameter, the description covers return content, input format and failure behavior adequately. It stops short of noting anything about very large pages or truncation, which is the only remaining gap for a doc-fetching tool.

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% and provides an example path, so the baseline is 3. The description goes further by stating that a site-relative path is expected and that a full docs.fictura.co URL is also accepted, which is behavior the schema's single example does not convey.

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 opens with a precise resource and return form: 'the complete markdown of one documentation page.' That clearly separates it from list_docs and search_docs, which yield collections, though neither sibling is named 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?

Usage is only implied: accepting a path (or a full docs.fictura.co URL) suggests this is the fetch-a-known-page tool after discovery via search_docs or list_docs, but the description never says when to prefer it over those siblings or what happens with a correct-but-stale path.

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 past the annotations: it explains the write is versioned rather than a blind overwrite, that history labels it `mcp: <note>` and can roll back, that live flows are rejected, and that translations, overrides and the exit setting survive. The destructiveHint=true is consistent with 'replaces' and is softened coherently by the versioning/rollback detail, so there is no contradiction.

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?

Three short sentences with no filler; the destructive replace behavior is front-loaded and the caveats (live-flow refusal, key requirement, preserved data) follow in a logical order.

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 destructive, nested-object mutation with no output schema, the description covers reversibility, permissions, rejection conditions and side-effect preservation. Nothing an agent needs in order to invoke it safely appears to be 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 meaning the schema doesn't: 'doc' must be the complete document (a replace, not a patch) and 'note' surfaces in version history with an `mcp:` prefix. That clarifies how to fill both required and optional params.

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 ('Replaces a draft flow's document') with the scope qualifier 'draft', which cleanly separates it from save_paywall_doc and from the editor_* pair. An agent can identify the tool and its target object 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 an explicit exclusion ('Refused for a live flow') and a prerequisite ('Needs an MCP key that can edit'), which is real guidance beyond the name. It stops short of naming the alternative to use for live flows or the validate_onboarding_doc / get_onboarding_doc siblings, so it is not a full 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?

Goes well past the annotations: it explains that the write happens as a new version, that History logs it as `mcp: <note>` and can roll it back, that products/translations/other settings are preserved, and that editing requires an appropriately scoped MCP key. The rollback detail importantly qualifies the destructiveHint=true annotation by showing the change is recoverable.

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 every clause (versioning, live-paywall refusal, auth, preserved settings) carries information an agent needs. The parenthetical version-history detail sits mid-sentence and the final clause is somewhat tacked on, so structure is good rather than exemplary.

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 destructive, non-open-world mutation with annotations present and 3 fully documented parameters, the description covers preconditions, side effects, reversibility and what is preserved. The only gap is that no output schema exists and the description says nothing about what the call returns (e.g. version id or updated doc reference).

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: `doc` is a whole-document replacement rather than a patch, and `note` surfaces visibly in History as `mcp: <note>`, which explains why the field matters. `id` semantics (must be a draft) are also reinforced.

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 ('Replaces a draft paywall's document') with the key qualifier that only DRAFT paywalls are accepted. It is clear what gets written, but it never names the closest sibling (editor_set_doc) or explains how it differs from that tool, so differentiation is only implicit via the draft/version wording.

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?

'Refused for a live paywall — copy it in the dashboard first' gives an explicit when-not condition plus the workaround, and 'Needs an MCP key that can edit' states the prerequisite. What is missing is any pointer to alternatives (e.g. editor_set_doc, validate_paywall_doc) for the cases this tool does not cover.

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 readOnlyHint/destructiveHint/openWorldHint, so the safety profile is covered; the description adds genuinely non-schema context: no API key required, docs are regenerated on every code change (freshness), and results are page paths rather than content. It stops short of describing ranking/pagination behavior, so not a full 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?

Three sentences, each doing distinct work: what it searches, when to use it, and what to do with the result. No redundancy and the key scoping/routing information is front-loaded.

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-parameter search tool with no output schema, the description supplies everything needed: the retrieval model, the auth requirement, the freshness guarantee, the return shape (page paths), and the natural next call. Nothing required to invoke 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% and both parameters (query, limit) are documented in the schema, so the description need not repeat them. It adds only the notion that matching is 'full-text' across the whole docs corpus, which is marginal value over the schema 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 and resource ('Full-text search across the Fictura docs') plus result shape ('grouped by page'). It also distinguishes itself from the adjacent list_docs/read_doc pair by noting it returns page paths that you then feed to read_doc.

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: 'Use this before answering any how do I… question' about a named set of domains (SDK, API, paywalls, entitlements, links, webhooks), with a rationale ('docs are the source of truth'). It also names the follow-up tool and why you'd use it, so 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?

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description's job is to add context. It adds the useful equivalence to list_error_issues, but says nothing about pagination, ordering, or the limit cap already implied by the schema.

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?

Two compact sentences with zero filler; the searchable-fields list is front-loaded and the list_error_issues relationship follows immediately.

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?

The return-value shape is partially handled by reference to list_error_issues, and there is no output schema to demand more. However, with 5 optional parameters and 20% schema coverage, the silent handling of status and limit leaves the definition incomplete for a filtering tool.

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 only 20% — just the query parameter is documented — so the description has to compensate. It does add meaning for release ("first or last seen in") and confirms query targets title/culprit, but status and limit get no explanation in either place.

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 (Find) and resource (issues), plus the exact fields searched (title/culprit, platform, release). It also explicitly distinguishes itself from list_error_issues by saying it returns the same rows, filtered, so an agent can pick between the two 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?

Mentioning that it returns the same rows as list_error_issues implicitly frames the choice (filter vs. list-all), but the description never states when to prefer this over get_error_issue or when filters are required. Usage is inferable rather than explicit.

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?

Adds substantial context beyond the annotations: runs in the background and survives the call, missing plan reports are skipped rather than failing, dedup ensures already-imported data is counted once, and concurrent invocation is safe. Annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false) already cover the safety profile, and the description complements rather than contradicts them.

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 single paragraph with the scope declaration front-loaded, then mode semantics, then concurrency/progress guidance. Every sentence carries information, though it is long enough that a bulleted split of mode/resume semantics would read more scannably.

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 background import with no output schema, the description covers scope, mode behavior, resume semantics, concurrency safety, partial-plan tolerance, and where to check progress. Nothing an agent needs to invoke 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, but the description meaningfully expands both parameters: it explains what 'auto' actually does (incremental from last finished import vs. full history on first run) and that resume=true restarts a failed/cancelled run from where it stopped, beyond the terse schema text.

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 (import) and resource (all AppsFlyer data for this app) and enumerates exactly what is pulled: installs, attribution chain, in-app events, purchases, uninstalls, reinstalls, ad revenue, retargeting. It is clearly distinct from the sibling get_appsflyer_import_status, which it explicitly names as the progress-inspection counterpart.

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 semantics for each mode: 'auto' (default) pulls days since last finished import or full history if none, 'full' re-walks everything, resume=true continues a failed/cancelled run. It also states the concurrent-call behavior (reports the running import instead of starting another) and routes progress checks to get_appsflyer_import_status.

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 that this is not read-only and not destructive, and the description adds a useful behavioral detail: the editor displays that the agent left. However, it does not explain reversibility, authentication requirements, idempotency, or what happens if the pairing is already ended.

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 two short sentences, front-loads the action, and every sentence contributes either the purpose or a visible side effect. There is no redundant or filler text.

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 simple one-parameter tool with full schema coverage and annotations, the description is adequate but minimal. It omits usage context and edge-case behavior, though the schema and annotations cover much of the structural and safety information.

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%, and the only parameter's schema description already says it comes from pair_editor. The tool description adds no further parameter meaning, so the high schema coverage makes 3 the appropriate 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?

The description states a specific action, stopping a pairing, and the title clarifies that the pairing is with the editor. It is clear enough to distinguish from most siblings, especially pair_editor, though the description alone relies on 'this pairing' rather than naming the editor 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?

The description says what the tool does but gives no explicit guidance on when to use it, when not to use it, or how it relates to alternatives such as pair_editor. The usage is only implied by the word 'Stops'.

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 state readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real value with the write-entitlement gate, but it does not clarify side effects such as whether status changes notify anyone, whether omitted fields are cleared, or whether re-assignment overwrites silently. A 3 reflects partial added context beyond 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?

Two tight sentences: the operations are front-loaded, followed by the prerequisite. No restated title, no filler, and 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?

For a six-parameter mutation with no output schema and no schema descriptions, the definition covers the main operations and the write gate, but leaves resolved_in_release undocumented and says nothing about what a successful response contains. It is adequate but has clear gaps given the schema's zero coverage.

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 0%, so the description must carry parameter meaning. It maps well to status (resolve/ignore/reopen), assignee, priority, and note, but never mentions resolved_in_release or clarifies that issue_id is a required UUID identifier. It compensates for roughly half the schema 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?

The description opens with concrete verbs tied to the resource: resolve, ignore, reopen, assign, set priority, add a note. That enumerates exactly the mutations available and clearly separates it from read-side siblings like get_error_issue and list_error_issues.

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-not condition: writes only work when the app enables MCP issue changes via Issues settings. It does not explicitly name an alternative for read-only inspection, but the prerequisite is a strong, actionable gating rule that most descriptions omit.

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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds real value by naming the three checks performed (parser, step-key check, renderer) and stating it reports what is wrong. It stops short of describing the shape of the report or the cost of running the renderer.

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?

Two tight sentences, with the core behavior and the no-side-effects guarantee front-loaded and zero filler.

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 a nested-object parameter and no output schema, the description tells the agent it gets back a report of problems 'if anything', which is enough to act on. A brief note on the report's shape or the requirement for a version-1 document would have made it complete.

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% for the single required `doc` parameter, so the schema already carries the semantics. The description adds no detail about the document structure (version 1, nested objects) beyond what the schema states, so 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 specific verb (validate/run through parser, step-key check and renderer) and resource (an onboarding document), plus the key scope qualifier 'changes nothing'. The comparison to 'the same parser ... a save uses' implicitly separates it from save_onboarding_doc, and the 'onboarding' qualifier distinguishes it from validate_paywall_doc.

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?

'Changes nothing' and 'the same parser a save uses' make the pre-save validation context clear without naming save_onboarding_doc explicitly. There are no explicit exclusions or a direct pointer to the sibling it complements, which keeps it out of the top band.

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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable context beyond that: it validates using the same parser and renderer as a save and reports what is wrong, clarifying that it mirrors real save behavior without mutating.

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?

Two compact sentences that front-load the core behavior and end with the key non-mutating guarantee. No wasted 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?

For a simple single-parameter validation tool with no output schema, the description is largely complete: it explains what is checked and that nothing changes. It could be slightly richer by hinting at the return shape (e.g., list of errors vs. a boolean), but annotations already carry the safety profile.

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 single 'doc' parameter is already documented in the schema as 'A paywall document (version: 1)'. The description adds no further parameter-level detail, which is acceptable given the high coverage 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 (validate) and resource (paywall document) with precise mechanics: it runs the document through the same parser and renderer a save uses. This clearly distinguishes it from save_paywall_doc and validate_onboarding_doc.

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?

Implies usage before saving by saying it uses the same parser and renderer a save does, and 'Changes nothing' signals it is a safe pre-check. However, it does not explicitly name save_paywall_doc or say when not to use it, leaving the alternative selection slightly implicit.

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