SaaS Pro Max

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

Adds real context beyond annotations: an internal permission-filtered tool loop, answers that cite the tools used, a prerequisite (configured AI provider), and a side effect the annotations don't capture (consumes provider credits). The notable gap is that destructiveHint=true is never explained – nothing warns the agent that the internal loop may perform writes or that repeated calls are non-idempotent and billed.

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 dense sentences (~50 words) with zero filler, leading with the action and following with mechanism, return shape, and cost prerequisites. Every clause carries information an agent cannot get from the 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 does the necessary work by stating the return value (a written answer citing tools used). Missing pieces for a destructive, open-world, credit-consuming tool are the failure mode when no AI provider is configured and any warning about mutating internal calls.

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 67% and the schema already documents both `app` (id or orgSlug/appSlug) and `conversationId`. The description only adds the single-application scoping constraint on the question; it says nothing about question length, phrasing, or what happens if conversationId refers to a different app.

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?

Specific verb+resource: asks a natural-language question to a SaaS Pro assistant, scoped to one application. It implicitly distinguishes itself from the structured-data siblings (get_metric_series, list_events, etc.) by describing an agentic NL layer, though it never names an alternative 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: an agent can infer this is for open-ended NL questions rather than precise data lookups, and the 'about one application' clue implies multi-app questions need multiple calls. There is no explicit when-to-use/when-not guidance relative to the many sibling query tools.

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 this as a destructive, non-read-only, open-world mutation, and the description adds useful context: it fires notifications to named channels and requires write scope plus metrics.write. It does not restate the destructive annotation, but it adds enough behavioral context beyond the structured hints.

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 three tightly packed sentences with no filler. The core purpose is front-loaded, followed by the condition caveat and the authorization requirement 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 complex create tool with a nested free-form `condition` object and no output schema, the description covers the most important non-obvious behavior: watched signal types, condition variation by kind, notification channels, and required scope. It is slightly incomplete on parameter details and alert lifecycle behavior, but it is usable as written.

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 low at 18% across 11 parameters, so the description carries significant burden. It usefully explains the otherwise opaque `condition` object with kind-specific shapes for metric, uptime, and vital rules, and it links `channelIds` to notification channels, but it leaves most other parameters such as `threshold`, `comparator`, `windowMinutes`, and `cooldownMinutes` to the schema alone.

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

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

The description states a specific verb and resource: create an alert rule. It also names the watched signal types and the firing destination, so its purpose is immediately distinguishable from read/list/update siblings.

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 by the create action and the mention of required write scope, but there is no explicit guidance on when to use this versus other alerting or incident tools, nor when not to use it. It provides prerequisites rather than selection 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 flag destructive and non-idempotent, and the description adds context annotations cannot carry: the secret is shown only once and never again, the required authorization scopes, and the capability difference between public and secret keys (event sending/flag evaluation vs. visitor IP and user agent). That is exactly the information an agent needs before minting a credential.

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, with the single-return-value warning placed before the key-type detail so the irreversible consequence 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?

No output schema exists, and the description covers the return behavior ('return its value exactly once'), the inputs' implications, and the auth requirements. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 75% and the enums are self-documenting, but the description still adds real meaning for 'kind' by explaining the consequence of each value rather than just 'public for browsers, secret for servers'. 'One environment' contextualizes the environment parameter; 'label' is not addressed.

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 ('Mint an ingest key for one environment') plus a distinctive behavioral fact ('return its value exactly once'). It also enumerates the two key kinds with their prefixes, which separates it cleanly from list_api_keys and the rest of the siblings.

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 clear selection guidance between the two kinds ('public key is safe in a browser bundle', 'secret key is server-only') and states the prerequisites (admin scope and keys.write). It does not explicitly name an alternative tool or say when not to call this, so it stops short of the top score.

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

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

Annotations already declare destructiveHint=true, non-idempotent and open-world, so the safety profile is covered. The description adds real context beyond that: the call provisions three environments as a side effect, slug is auto-derived unless supplied, and the exact auth scopes required. It doesn't restate the irreversibility of the operation, which annotations 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 tight sentences, front-loaded with the action and its environment side effect, then slug behavior, then auth. Every sentence carries actionable information; the docs link is a cheap pointer 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?

With no output schema, the description doesn't indicate what comes back (e.g. the created app id/slug), which an agent may need for follow-up calls like get_app. Everything else — auth, side effects, required name/org, slug derivation — is adequately covered for a 6-parameter creation 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 description coverage is 83%, so the schema already documents org, name, slug, url, modules and platform; baseline is 3. The description restates the slug default (already in the schema) and mentions the name, but says nothing about url, modules or platform, so it adds little beyond structured fields.

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?

Specific verb + resource ("Create an application inside an organization") plus a notable scope detail: it also provisions production, staging and development environments. That side-effect scope clearly separates it from get_app and list_apps, which read a single app or enumerate apps.

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 prerequisites ("Requires a token with the write scope and the apps.write permission") and explains the name/slug choice, which tells the agent how to call it correctly. It stops short of explicit when-not guidance or naming siblings like get_app for the read path, so it is clear context without exclusions.

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 genuinely useful context beyond the annotations: it names the required scopes ('write scope and analytics.write') and explains the counting semantics (step n+1 only counts when the same person did it after step n within the conversion window). It does not address why destructiveHint=true applies or what a re-save would overwrite, but the annotations already flag the safety profile.

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 constraints before the semantics. Dense but no filler; each sentence adds a distinct layer (what, how steps count, what scopes are needed).

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

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

Covers the creation semantics, the nested step structure, and the auth requirement for a destructive mutation with no output schema. It doesn't describe what is returned (e.g. the funnel id) or clarify the destructive/re-save behavior, which would round it out.

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

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

With schema coverage at 40%, the description compensates on the hardest parts: 'two to twelve steps' mirrors the minItems/maxItems, 'event name or an exact path' maps to the kind enum, and the utm_source-equals-facebook example plus 'after step n... inside the conversion window' give meaning to filters and windowHours. Only app, name, and description remain undocumented, but they are largely self-evident.

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 ('Save an ordered funnel') and immediately bounds it with the 'two to twelve steps' constraint. The remaining sentences define what a funnel step is, so an agent can tell this is a create-a-funnel tool. It stops short of naming the read-side siblings (list_funnels, get_funnel_results) for contrast.

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?

'Save' plus 'Requires the write scope' implies this is the mutation path used once you know your funnel steps. But the description never explicitly says when to use this versus list_funnels to read an existing one or get_funnel_results to analyze, so the routing to 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 declare destructiveHint, openWorldHint, and idempotentHint=false, so the safety profile is partly covered. The description adds meaningful context beyond that: tenant permissions, scopes, validation, and audit remain enforced, and console-only/external actions are gated by approval — material behavior an agent needs before firing a write.

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 its prerequisite, and no filler beyond the mildly redundant "Supports application settings and other API writes." Every other clause carries real constraint 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?

The discover-then-execute loop and enforcement boundaries are covered, which is the core need for a generic API executor. However, with no output schema and no statement about what a successful execution returns (or its failure shape), an agent still cannot predict the response of a destructive, non-idempotent write.

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 baseline is 3; each parameter is already documented in-schema (operationId from get_api_capabilities, body matching bodySchema, named path/query params, env for environment). The description adds no parameter-level detail beyond hinting that the contract comes from discovery.

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

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

States a specific verb+resource ("Perform a Management API change") and scopes it to operations whose contract was discovered via get_api_capabilities, which cleanly separates it from the discovery sibling. The brief phrase "application settings and other API writes" is vague about the full scope and never contrasts it with the read sibling read_api_operation, keeping it 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?

Gives a concrete prerequisite workflow: use get_api_capabilities first, then execute what the user explicitly requested. It also sets a boundary (console-only destructive or external actions cannot bypass approval). It stops short of naming explicit when-not-to-use conditions or pointing at read_api_operation for non-mutating cases.

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

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

Beyond the annotations, the description discloses the approval workflow, the requirement for a matching authorizationId, current membership, token scope and a fresh passkey session, and that destructive/external/privileged actions retain domain safeguards. This adds substantial operational context that annotations alone do not convey.

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

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

The description is front-loaded and has no wasted framing, but the second sentence is dense and packs multiple authorization constraints into one long clause. It remains readable and appropriately sized for a complex 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 destructive, open-world command execution tool with eight parameters and no output schema, the description covers the critical usage path, approval requirement and prerequisite checks well. It does not describe the execution result or failure behavior, which leaves a minor completeness gap.

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

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

Schema coverage is already high at 88%, but the description adds useful cross-tool semantics: fields, target and reason must match those used by prepare_command, and authorizationId is omitted only for direct commands. It does not add much about commandId, org, app, environment or files beyond the schema, so it is not a full 5.

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

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

The description states a specific verb and resource ("Execute a command") and immediately distinguishes routine direct execution from approval-gated execution. It names sibling tools get_command_schema and prepare_command, so an agent can tell how this tool fits with them without opening other definitions.

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 clearly says a routine command marked execution: direct runs immediately without authorizationId, while any other command requires approval and an authorizationId from prepare_command. The routing is strong, though it does not explicitly spell out the full call sequence or state what to do if prepare_command has not been called.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds real value beyond that: deduplication semantics across the window, the DAU/MAU stickiness formula, and per-day granularity of rolling windows — behavioral context the annotations do not 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?

Two tight sentences: the first front-loads what is returned, the second adds the differentiating semantics. No filler, no restatement of the title.

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 does the necessary work of naming the returned series (DAU/WAU/MAU plus stickiness per day). Given 100% schema coverage and rich annotations, little else is needed; only the relationship to sibling analytics tools is left unstated.

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 app, range, filters and environment are all fully documented in the schema. The description only lightly echoes the range parameter ('for each day in the range') and adds no syntax or default detail, which is the correct baseline when the schema does the work.

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 the specific resource (daily/weekly/monthly active users) plus the derived metric stickiness with its formula, so the agent knows exactly what data comes back. The contrast with 'visitors' hints at what it is not, but no sibling tool is named, so differentiation is implicit rather than explicit.

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 'Unlike visitors these are deduplicated... and measure ongoing engagement' clause implies when this tool is preferable to a visitor-counting read, but there is no explicit when-to-use, when-not-to-use, or named alternative among the many analytics siblings (get_metric_series, get_timeseries, get_analytics_overview).

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description's only added behavioral detail is that each metric carries a previous-window equivalent and percentage delta, which is useful output context but not rich operational transparency.

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 enumerates the returned metrics with zero filler. Every clause carries information an agent can use.

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 a read-only tool, the description usefully lists the returned metrics and the comparison/delta structure, and the schema fully covers input parameters. What remains missing is the routing/alternative guidance needed to distinguish it from the many 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 all four parameters (app, range, filters, environment) are fully documented in the schema, including range syntax and filter semantics. The description adds nothing beyond 'for a range', 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?

States a specific verb+resource ('Headline web analytics for a range') and enumerates exactly which metrics are returned, so an agent knows what it gets. However, it never names or contrasts the obvious siblings (get_breakdown, get_timeseries, get_metric_series, get_revenue_overview); 'headline' implies a summary but the 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 implied by the word 'Headline', suggesting a top-level summary rather than a per-dimension or time-series drill-down, but no explicit when-to-use or when-to-prefer-alternatives guidance is given. An agent must infer the boundary with get_timeseries/get_breakdown on its own.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description usefully adds that operationId yields the full path/query/body contract, but says nothing about pagination behavior (limit/offset with a hard cap of 50) or the shape of list results, which matters for an open-world discovery tool.

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 doing distinct work: what it returns, how to query it, when to call it and where to go instead. No repetition of the title 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 read-only discovery tool with no output schema, the description covers purpose, query modes, escalation path and the fallback rule. The one gap is pagination: with limit capped at 50 and offset available, an agent is not told that results may be truncated or how to page through them.

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

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

Schema description coverage is only 25% — only 'search' is documented in the schema. The description compensates by explaining both ambiguous parameters: search takes plain words, and operationId returns that operation's full path/query/body contract. limit and offset remain undescribed, though they are conventional pagination names.

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 ('Discover all current Management API operations') and narrows the scope by noting it covers settings and modules absent from the dedicated tools. The mention of plain-word search and operationId lookups makes the two modes of use unambiguous.

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?

'Call this before saying an action is unsupported' gives an explicit trigger condition, and the final sentence routes protected actions away to list_commands. That is a named alternative with the condition that selects it, not implied usage.

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, idempotentHint, openWorldHint, and destructiveHint=false. The description adds useful behavioral context by listing returned fields and warning that disabled modules cannot be accessed, though it does not address auth or error behavior.

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 concise sentences with the core action front-loaded and no wasted wording. The returned-field list and access caveat are both relevant.

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 read-one tool with one fully documented parameter, safety annotations, and no output schema, the description provides enough context: it names the resource, enumerates returned fields, and notes the disabled-module access constraint.

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 schema has 100% description coverage and explains that the app parameter accepts an application id or orgSlug/appSlug as returned by list_apps. The description adds no parameter-specific detail beyond the schema, 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 verb and resource: reading one application. It also scopes the operation to a single app and enumerates the fields returned, which distinguishes it from the sibling list_apps tool.

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

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

The single-app scope implies when to use this tool instead of list_apps, but the description does not explicitly name alternatives, prerequisites, or exclusions. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the safety profile needs no restating. The description adds the ranking metric (visitors) and that results are per-dimension, but says nothing about result size, default limit, or how the top-N cutoff interacts with filters. The capped/filter-shortening behavior is documented in the schema, not the description.

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 leads with the core operation. The long dimension list is somewhat redundant with the dimension property's own enum text and is the only part that doesn't earn 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?

With 7 parameters, no output schema, and no default stated for limit, an agent lacks detail on what comes back (values plus visitor counts? share?) and how 'top' is bounded. The description is adequate for choosing the tool but thin for predicting its output.

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 71%, so most parameters are documented in-schema. The description's dimension enumeration duplicates the dimension property description rather than adding meaning, and the undocumented parameters (limit, search) get no explanatory help. 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?

States a specific verb+resource: returns top values for one analytics dimension, ranked by visitors. The enumerated dimension list makes the scope concrete. It doesn't name which sibling to use instead (get_timeseries, get_analytics_overview), but the operation itself is unambiguous.

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 by 'top values ... ranked by visitors' — an agent can infer this is the categorical breakdown tool. There is no explicit when-to-use/when-not, no mention of when to prefer get_timeseries, get_metric_series, or get_analytics_overview 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 readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely new context by enumerating the exact metric fields returned and the app/environment scoping rule — valuable since there is no output schema. It does not cover behavior when the campaignId is unknown or not in the given app.

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 filler, with the resource and the returned fields front-loaded before the scoping note. Nothing repeats the title or wastes tokens.

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, enumerating the stat fields in prose is exactly the right compensation, and scope is stated. Gaps remain around not-found behavior and whether campaignId is app-scoped, but for a read-only single-record lookup the description is otherwise sufficient.

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 67%: app and environment are already documented in the schema, and the description merely echoes that the result is scoped by them without adding format or default details. campaignId remains undocumented in both places, though the resource is unambiguous.

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 (one campaign) and enumerates the statistics returned, which is far more than restating the name. It implicitly contrasts with list_campaigns by specifying a single campaign, but never names that sibling, so 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?

"Results are scoped to the selected application and environment" implies you must already know the app/environment context, but there is no explicit when-to-use guidance versus list_campaigns (to find the id) or get_analytics_overview / get_breakdown (for cross-campaign aggregates). Usage is implied rather than 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, idempotentHint, and non-destructive, so safety is covered; the description adds genuinely new behavioral context by stating that approval applies once to the exact target and input and by warning against automatic re-approval after an uncertain execution. It doesn't disclose what the response contains or how long states persist.

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 operation and the state enumeration, followed by the two operational cautions. The state list is long but load-bearing since it defines the return values; no filler sentences.

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 carries the return-value burden and does it by enumerating all eight possible states. Combined with the approval-semantics and no-auto-retry caveats, an agent has enough to poll and react correctly without additional context.

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 is expected to compensate for the single authorizationId parameter. It only implies provenance via 'this token's prepared command', without saying where the id comes from (presumably prepare_command) or how to handle unknown/expired ids; the format is enforced by the schema pattern 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?

Specific verb ('Read whether') plus the exact resource (a prepared command's authorization status), and it enumerates every possible state, so the agent knows precisely what it gets back. It does not name the sibling workflow tools (prepare_command, execute_command) explicitly, so differentiation is implied rather than stated.

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 clear conditional rule — a completed or uncertain execution must be inspected rather than retried with a new approval automatically — which is real when/when-not guidance. It stops short of explicitly routing to execute_command or prepare_command as alternatives, leaving the workflow linkage to inference from 'this token's prepared command'.

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, idempotent, non-destructive), so the description adds real value beyond them: the values are the same validators and business actions used by the console, passkeys and two-person approvals remain enforced, and discovery does not confer access. That is useful trust and side-effect context for an agent deciding whether this read is sufficient.

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 action stated first and the security caveat second. Slightly dense phrasing ('authoritative fields, permission and approval requirements') but 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 single-parameter read-only tool with no output schema, the description conveys what is returned (fields, permissions, approval requirements) and that no access is granted. Adequate; an explicit note on the shape of the returned schema would be the only remaining 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?

One required parameter with 100% schema description coverage, including the pattern and the hint to source the id from list_commands. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource: reads the authoritative fields plus permission and approval requirements of a shared application command. It is clearly distinct from the listing sibling list_commands (which the schema points back to), though it never explicitly contrasts with get_command_authorization or prepare_command, the closest alternatives.

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?

'discovery never grants access' implies this is an inspection step, not an execution step, and the schema's 'Exact id from list_commands' tells the agent where to get the input. But there is no explicit when-to-use/when-not guidance and no named alternative for authorization checks (get_command_authorization) or execution (execute_command).

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the tool only returns requirements, it does not turn on collection, and actual code deployment is a separate step — a common source of agent misunderstanding.

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 deliverable comes first, the caveat about deployment second. Every clause carries information an 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?

Read-only, two fully documented params, no output schema — the description compensates by enumerating what the instructions cover. Only minor gap is it doesn't indicate the shape/format of the returned instructions (code snippets vs. prose), but nothing needed 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 description coverage is 100% and both parameters (app, environment) are documented in the schema, including the orgSlug/appSlug form and the environment default. The description adds no parameter-level guidance, 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?

Specific verb+resource: returns server-side integration requirements for Cookieless visitors, and enumerates the contents (trusted visitor IP handling, public paths, opt-outs, secret ingest keys, verification). This clearly separates it from get_install_instructions and from get_cookieless_report/get_cookieless_status, though the sibling distinction is left implicit rather than named.

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?

Clear context for use — setting up cookieless collection — plus an explicit negative: 'this tool does not enable collection by itself' and deployment in site code is required. It stops short of naming the alternative tool (e.g. get_install_instructions for standard installs) or stating prerequisites such as which app/environment to query.

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, idempotent, non-destructive, openWorld), so the description's job is data semantics — and it delivers: counts are daily visitor estimates, a person may be counted again across midnight, and these are not persistent people or lifetime uniques. That is exactly the kind of caveat that prevents misreading a report.

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 filler. The scope-and-purpose sentence comes first, the important data caveat second — properly 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 read-only report tool with no output schema and modest parameter complexity, the description covers what is returned at a high level (counts, history, breakdowns) plus the interpretive caveat. The missing piece is any hint of response shape or granularity for history/breakdowns, but annotations carry the rest.

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 67%: app and environment are documented in the schema, while range is only an enum with no prose explanation. The description adds no parameter-level detail beyond restating 'one application and environment', so it neither compensates for the range gap nor adds meaning 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 ('Read') and a specific resource ('Cookieless visitors counts, history and breakdowns') scoped to one application and environment. That distinguishes it from generic siblings like get_analytics_overview or get_breakdown, though it never names those siblings 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 word 'separate' implies this is a distinct cookieless data source rather than the general analytics endpoints, which is a useful usage hint. But there is no explicit when-to-use/when-not, no mention of get_cookieless_status or get_cookieless_install_instructions as adjacent tools, so selection is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: there is no toggle to read, and the check is a diagnostic of whether server-side pageviews are arriving, which prevents the agent from misreporting collection as enabled. It doesn't say what the response contains or whether results can be stale.

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 is checked, then the crucial 'no on/off toggle' caveat, then the operational instruction. Nothing is padded or redundant.

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 some burden for explaining what a status result conveys; it does this at a high level (collector receiving data, Analytics available, ingest key available) but doesn't describe the shape or possible values. For a two-parameter read-only diagnostic it is otherwise complete enough to call 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 description coverage is 100%, so the app and environment parameters are already documented, including the production default and the orgSlug/appSlug format. The description only reinforces that the check is per-app ('check each app'), which is marginal added meaning. 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 gives a specific verb ('Check whether') and a precise object ('an application's Cookieless visitors collector is receiving data'), plus the secondary checks for Analytics and server ingest key availability. That is far more informative than the title alone. It does not explicitly contrast itself with the nearby get_cookieless_report or get_cookieless_install_instructions tools, so an agent must infer the split from names.

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?

'Check each app before claiming collection is enabled' gives a clear trigger condition and implies per-app iteration. The key usage caveat — that there is no on/off toggle and forwarding is the responsibility of the website — is stated. It stops short of naming alternative tools or describing when this check is unnecessary.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds value beyond that by disclosing the shape of what is returned in each of the two modes. It doesn't cover behavior when the issue or event id doesn't resolve, or whether daily counts are bounded.

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 default behavior before the alternative mode, and every sentence carries information. The trailing field enumeration is dense and slightly awkward ("the request and the person and session ids") but not wasteful.

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 four-parameter read tool with no output schema, the description does the heavy lifting by listing the returned fields in both modes, which is exactly the gap an output schema would otherwise fill. It falls short only on the unexplained issueId and on failure/not-found behavior.

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

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

With 75% schema coverage the baseline would be 3, but the description genuinely adds meaning for eventId (it switches the whole read mode, and the id must be sourced from the events list) rather than restating the schema. issueId remains semantically unexplained in both schema and description, which holds it below 5.

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+resource (read one error issue) and enumerates exactly what comes back (title, culprit, level, status, first/last seen, daily counts, releases, tags). It also carves out the second mode via eventId, so an agent can distinguish it from list_errors or update_error_status without opening the schema.

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

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

It states an explicit conditional: pass eventId to read a single occurrence instead of the issue summary, and tells where occurrence ids come from (the issue's events list). What's missing is an explicit when-to-use-this-vs-list_errors boundary, so it's clear context rather than full routing.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context by explaining the output shape and the row invariant converted + dropOff = entered, which is not derivable from 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?

Two sentences, tightly front-loaded with the resource and result shape, then followed by the row arithmetic invariant. Every sentence carries useful information with no repetition or 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 adequately explains the returned metrics and row-level invariant. Annotations cover safety and idempotency, and the schema covers most parameters; the main remaining gap is that funnelId's source and format are not clarified.

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 75%, with app, range, and environment documented in the schema. The description does not compensate for the undocumented funnelId parameter by naming its source (e.g., list_funnels) or format, though it does add the context that the funnel must be a saved funnel.

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 and scope: step-by-step conversion for one saved funnel over a range, including entries, continuations, conversion rate, and drop-off. It distinguishes this from list_funnels and create_funnel by focusing on results for a single saved funnel, though it does not explicitly name sibling alternatives.

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 guidance on when to use this tool versus alternatives such as list_funnels, get_breakdown, or get_retention. It implies the tool is for retrieving results from an already saved funnel, but no when/when-not conditions or prerequisites are stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower. The description adds genuine context beyond that: snippets use the real key prefix and host, follow published SDK APIs, and clarifies that browser identity modes do NOT enable the separate Cookieless visitors report.

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 capability. The framework enumeration is long but functional; no padding sentences.

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

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

For a 4-param read tool with 75% schema coverage and no output schema, the description covers purpose, frameworks, and the key caveat. It doesn't detail the return format, but 'snippets' is self-evident and everything an agent needs to call it is present.

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 75%, so the schema already documents most params. The description still maps the framework enum values explicitly and clarifies the privacyMode semantics ('Browser identity modes do not enable the separate Cookieless visitors report'), adding meaning beyond the schema.

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

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

The description names a specific resource (copy-paste install snippets) and enumerates the exact frameworks covered, using the app's real key prefix and host. This clearly distinguishes it from the sibling get_cookieless_install_instructions and other install/report 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?

The framework list implies when to use it, but there is no explicit when-to-use/when-not language or routing to alternatives. The final sentence about Cookieless visitors hints at a boundary with the cookieless tool but frames it as a caveat rather than an explicit 'use X instead' instruction.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces that ('nothing is ever changed in Meta'). It adds genuinely non-structured behavior: units (amounts are hundredths of the account currency, rates are fractions) and data provenance (visits/engaged visits/time-on-site joined from utm_term, plus a wasted flag). It does not disclose row limits, pagination, or latency, which keeps it below 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 resource and its dimensions, then usage, then units. Dense but every clause carries information; the long first sentence is the only mild readability cost.

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 listing the breakdown dimensions, the joined site metrics, and the currency/rate units. Missing are result size, ordering, or pagination behavior, which an agent would want for a multi-dimension breakdown query.

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 app, range, source, and environment thoroughly, including enum meanings and defaults. The description adds only indirect context (currency comes from the ad account, placement keyed via utm_term) and never clarifies parameter behavior itself, 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 first sentence names a specific verb+resource (Meta ad spend and clicks) and enumerates the exact breakdown dimensions returned: placement, publisher platform, device, country, age, gender. It is clearly distinguishable from get_meta_ads_overview and get_breakdown by naming Meta-specific dimensions, though it never explicitly contrasts itself with those siblings.

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 decide which placements to exclude' gives one concrete decision context, which is more than nothing. But there is no when-not guidance, no mention of get_meta_ads_overview or get_breakdown as alternatives, and no prerequisites (e.g. requiring a connected Meta ad account) beyond the parameter defaults.

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, idempotentHint and destructiveHint=false, so the closing 'read-only: nothing is ever changed in Meta' adds modest assurance rather than new information. The genuinely additive disclosure is the unit contract — amounts in hundredths of the ad account's currency, rates as fractions — which prevents a costly misinterpretation of every returned number. No mention of auth needs, rate limits or response size, but the unit semantics are the higher-value disclosure here.

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?

Structure is strong: the content inventory comes first, then the units contract, then the safety note — three distinct concerns in three sentences with no filler. The first sentence is long and list-dense, but every item in it is a returned field an agent would otherwise have to guess at, so 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?

With no output schema, the description correctly carries the burden of describing returns, and it does so thoroughly, including units and both series granularities. The main omission is coverage of the 'range' parameter's launch/today/yesterday/7/30 options in prose, and any hint of response shape or volume for a tool that returns daily and hourly series plus budgets.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining what the 'hours' window means semantically — each window is compared against the same span before and since launch — which is reasoning the enum description does not spell out. It does not mention 'range' values (today, yesterday, 7/30 days), 'source' selection or 'environment', but those are fully documented in the schema.

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

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

Names a specific resource (Meta Ads account) and enumerates exactly what the overview contains: spend, impressions, reach, link clicks, landing page views, results/cost per result, hourly and daily series, budgets with pacing and learning phase, and the issues list. An agent can distinguish this consolidated overview from narrower siblings such as get_meta_ads_breakdowns, get_campaign_stats or list_meta_ads_issues 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?

Usage is implied by the content inventory — you can infer this is the headline dashboard tool — but there is no explicit when-to-use or when-not-to-use guidance relative to get_meta_ads_breakdowns, get_metric_series, get_analytics_overview or list_meta_ads_issues. The gap is most visible around the issues list, which is offered here yet also has a dedicated sibling, with no rule for choosing between 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 read-only, idempotent, non-destructive semantics, so the description is not needed for the safety profile. It does add genuinely useful behavior beyond annotations: short ranges return raw points while longer ranges return five-minute rollups, and the response discloses which in `source`. It stops short of saying when the rollup boundary kicks in or how dense the buckets become.

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 no filler: the first defines the operation and its options, the second explains the resolution behavior. Front-loaded and appropriately sized for the tool's complexity.

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, it usefully mentions the `source` field in the response, covering the main return-value concern. For a 7-parameter tool with only 2 required, however, it leaves defaults for `agg` and `interval` and the interaction between `range` and `interval` unexplained.

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 57%, and the description largely restates the agg enum and label filtering that the schema already defines. Its one real addition is explaining that `range` changes data resolution (raw vs five-minute rollups), which gives that parameter meaning the schema lacks. The `interval`, default agg and environment parameters get no additional explanation.

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 operation: aggregating a single metric into time buckets, with the exact aggregation functions and label filtering named. It is clear what the tool returns, but it never distinguishes itself from the close sibling get_timeseries (or list_metrics), so an agent cannot tell which to pick from the 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?

There is no explicit when-to-use or when-not-to-use guidance, and no mention of the obvious alternatives get_timeseries, get_breakdown or list_metrics. Usage is only implied by the fact that it works on 'one metric', which an agent could also infer from the 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 establish that this is a safe, read-only, idempotent operation, and the description adds a valuable behavioral caveat: emails and names are masked unless the caller has people.pii.read. This PII-permission dependency is exactly the kind of context annotations do not provide.

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 tight sentences, front-loads the dossier contents, and immediately follows with the important PII caveat. There is no redundant or filler language.

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-record tool with no output schema, the description gives a useful summary of returned fields and the PII masking condition. It could say more about missing-record behavior or the app/personId relationship, but the annotations and schema cover most remaining needs.

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 67%, with descriptions for app and environment but none for personId. The description does not add parameter-level detail beyond implying single-person retrieval, so the schema remains the primary source of parameter meaning.

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

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

The description clearly identifies the resource as one person's dossier and lists the kinds of data returned, so an agent can tell this is a single-person read rather than a list or search. It does not explicitly name sibling tools like search_people or update_person, so it falls short of full sibling differentiation.

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 required personId implies retrieval for a known person, but the description gives no explicit guidance on when to use this tool versus search_people or update_person. There are no stated preconditions, exclusions, or alternatives.

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 readOnly/idempotent/non-destructive, and the description adds genuinely non-obvious behavior: incomplete cells carry complete=false and don't represent a finished period. It does not mention rate limits or the default cohort/range behavior beyond what the schema states.

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, zero redundancy, with the core cohort behavior front-loaded ahead of the edge-case caveat about complete=false.

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 flags the two contract-level facts an agent needs (complete=false cells, capped filters). It stops short of describing cohort structure or default range behavior, which would make the return values fully predictable.

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 75%, so the baseline is 3; the description earns above that by explaining what the mode enum actually means (first match uses retained history, recurring admits once per period) and tying incomplete cells to the output. startEvent, cohortBy and environment are left entirely to the schema.

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

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

States the resource and analytic shape precisely: 'Action-based retention in daily, weekly or monthly cohorts', which distinguishes it from metrics/timeseries siblings. It never explicitly names an alternative or states the boundary vs get_funnel_results or get_active_users, so a 4 rather than 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?

Explains the two cohort modes but never says when to choose retention over a funnel or active-users query, nor when first vs recurring applies. Usage is implied by the mode semantics rather than given as 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 safety (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description nonetheless adds real behavioral context: results include a previous window for comparison, and all monetary amounts are in cents of the reporting currency — both non-obvious and material to interpreting output.

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 sentence plus a unit caveat, front-loaded with the metric inventory and no filler. Every clause conveys either scope or output semantics.

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 does the necessary work of enumerating what comes back and fixing the unit convention. The remaining gap is how the comparison window is presented in the payload and when this beats sibling analytics tools, but the essentials for calling it correctly are present.

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 accepted range formats and environment defaults already documented, so the schema carries the parameter burden. The description adds only an indirect hint that the range parameter drives a comparison window; it adds no new syntax or constraints.

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 (revenue) and enumerates the exact metrics returned: MRR, ARR, active/trialing subscriptions, new/expansion/contraction/churn movement, payments and refunds. That enumeration clearly scopes it apart from generic siblings like get_analytics_overview or get_metric_series, though it never explicitly distinguishes itself from them.

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 when-to-use guidance at all — no statement of which questions this answers versus get_analytics_overview, get_breakdown, or get_timeseries. The agent must infer applicability purely from the metric list, and there are no exclusions or prerequisites (e.g., required app scope) mentioned.

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 idempotentHint, so the safety profile is covered. The description adds genuinely useful behavior: the series is dense and empty buckets are returned as zero rather than gaps, which affects how results must be interpreted.

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, front-loaded sentences with no filler; the purpose leads and the zero-fill clarification follows. Slightly dense phrasing ('dense series') but nothing wasted.

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

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

There is no output schema, so the description carries the burden of explaining the return value; it does convey the series shape and zero-fill rule but says nothing about pagination, point count, or interval defaults.

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 67% and the range, filters and environment parameters are documented well in the schema, including the 90-day filter cap and capped flag. The description only restates the metric enum values, adding no format detail beyond the schema.

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

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

States a specific action and resource ('one analytics metric bucketed over time as a dense series') and adds the key zero-fill semantics. It does not differentiate from the closely named sibling get_metric_series, leaving an agent to guess between them.

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 no when-to-use or when-not guidance and never mentions alternatives such as get_metric_series, get_breakdown, or get_analytics_overview. Usage is only inferable from the description of output shape.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes beyond them by disclosing that key values are never returned (only prefix and last four) and that the admin scope is required — exactly the kind of context an agent can't infer from annotations.

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

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

Two tight sentences: the returned fields come first, then the security caveat and auth requirement. No filler, nothing repeated from the title.

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 fields returned (kind, environment, prefix, last four, revocation state) and clarifying that values are masked. Combined with the auth requirement, an agent has everything needed to call this correctly and interpret the result.

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

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

Schema coverage is 100% and the single `app` parameter is fully documented in the schema, including the orgSlug/appSlug alternative. The description adds no additional parameter meaning, 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?

Names a specific verb and resource (list an application's ingest keys) and enumerates the returned attributes, so the agent knows exactly what it gets. It implicitly distinguishes itself from create_api_key via the read-only framing, but never names a 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?

States the admin-scope precondition, which is genuinely useful gating information. However, there is no explicit when-to-use vs. when-not-to-use guidance or reference to alternatives such as create_api_key or execute_api_operation, leaving the routing to inference.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by listing returned fields and explaining that both returned identifier forms are accepted by other tools.

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 efficient sentences with no filler. The core listing behavior is front-loaded, and the second sentence adds a high-value interoperability note.

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 by naming platform, URL, enabled modules, environment ids, and the two app identifier forms. Combined with complete schema coverage for the only parameter and annotations covering safety, it is complete for this 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 description coverage is 100%, and the lone `org` parameter is already documented as an organization slug or id from list_organizations. The description reinforces the organization scoping but does not add syntax or format details beyond the schema.

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

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

The description states a specific verb and resource: 'List the applications in one organization.' It also names the returned fields, making it clearly a discovery/list tool rather than a single-app retrieval tool like get_app.

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 provides clear context: use this to list apps within an organization and obtain identifiers accepted by every other tool's `app` argument. It does not explicitly name alternatives such as get_app or list_organizations, so it stops short of 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 declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds real context beyond them by explaining the authoring/approval workflow limitation and the passkey requirement. It does not mention pagination behavior despite a limit parameter, 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?

Two tight sentences: the payload is front-loaded, then the critical API constraint. 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 no output schema, the description must convey return shape, and it does (campaign attributes plus a per-status count). It omits pagination behavior and the default ordering/size, which matters for a tool with a limit parameter.

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 75% and the schema documents app, status values, and environment default, so baseline is 3. The description adds only the framing that all results are scoped to one application and that status filtering produces the per-status count, without clarifying limit or status semantics beyond the schema.

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

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

The description names the resource (campaigns), the scope (one application), and the return payload (status, channel, audience, delivery statistics, plus a per-status count), which is well beyond the tautological title. It stops short of naming the closest sibling (get_campaign_stats), so the agent still has to infer the boundary between listing campaigns and fetching one campaign's stats.

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 second sentence gives a clear when-not condition: authoring and approval are impossible over this API path because they require a second operator and a fresh passkey. That prevents the agent from attempting a mutation via this listing tool. It does not, however, explicitly route to get_campaign_stats for single-campaign metrics.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds value beyond that: results are paginated, and each command indicates whether it runs directly or requires member approval — a non-obvious constraint for a read tool. It doesn't mention rate limits or result size limits, keeping 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?

Three sentences, each doing distinct work: scope, usage imperative, and operational caveat plus next-step pointer. The most important routing guidance ('search here before saying unavailable') is front-loaded with 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?

There is no output schema, and the description compensates by describing the shape of results (paginated, each command's direct-run vs approval status). The main residual gap is search-parameter behavior and whether pagination has a documented page size, but an agent has enough to call and interpret the 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 description coverage is 0%, so the description must carry the three parameters. 'Results are paginated' implies limit/offset but gives no ranges or defaults, and the 'search' parameter — the primary discovery lever — is never explained (what fields it matches, substring vs exact). Most parameter meaning is left to the agent to guess.

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

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

States a specific verb+resource ('Discover actions') with explicit scope ('across every application module and organization administration') and differentiates from siblings by saying it covers features 'missing from dedicated tools or REST routes'. An agent can distinguish this from list_apps/list_metrics/execute_command without opening a schema.

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

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

Gives an explicit when-to-use rule ('Search here before saying a setting or action is unavailable') and an explicit sequencing rule ('read get_command_schema before running or preparing a change'), naming the sibling tool to use next. Both the use case and the adjacent step are spelled out.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuine value beyond that by disclosing the row shape (a seven-day sparkline per issue) and explaining what it is for — distinguishing new from long-standing problems — 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, no filler, with the scoping constraint and filter/sort axes front-loaded before the return-value note. 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?

For a 7-parameter list tool with no output schema and low schema coverage, the description covers purpose, filters, sorts, and row content but omits pagination (cursor/limit) behavior and the q search parameter. An agent can call the basic case correctly but would be guessing at paging and text search.

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

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

Schema description coverage is only 29%, so the description must compensate; it does partially, spelling out the status values (open/regressed/resolved/ignored/all), the four sort keys, and the app+environment scoping. It leaves the free-text q parameter, the limit cap, and the cursor pagination entirely undiscussed in either schema or description.

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 exact resource (error issues) and its mandatory scope (one application and environment), plus the filter and sort axes. It is clearly distinguishable from get_error or update_error_status by being a listing operation, though it never names those siblings 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 implied by "filtered by status ... and sorted by ...", which enumerates the supported query modes, but there is no explicit statement of when to choose this over get_error, list_incidents, or the analytics tools. No prerequisites, exclusions, or alternative routing are given.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine value by disclosing the shape of the payload (counts plus unique-person counts) and the caveat that names reflect received events, but it says nothing about result volume, pagination, or truncation.

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 with no filler, and the most important fact — what the rows contain — comes first. It is efficiently sized, though the second sentence ('Names reflect received events') is terse enough to be ambiguous rather than clarifying.

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 does partially meet it by describing name, count and unique-user count. However, it omits how results are ordered, whether counts are approximate, and how many names can come back, which matters for a cardinality-exploding list endpoint.

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 range, filters, environment and app are already fully documented, including the custom range syntax and the filters' 90-day cap. The description adds no parameter detail beyond the schema, which is the expected 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?

The description names a concrete resource (event names) and spells out the returned fields — occurrence count and distinct people — so an agent knows exactly what the call produces. The verb 'list' is only implied by 'Every event name seen', and it does not explicitly separate itself from the sibling list_events, which reads similar enough to cause hesitation.

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 says the names come from 'the range' but gives no when-to-use framing, no prerequisites, and never mentions list_events or get_breakdown as alternatives for event data. An agent must infer from the tool name alone when this is the right choice over other event-listing tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds genuine behavioral value with the newest-first ordering and the note that search matches across name, path, url, distinct id and properties. It says nothing about pagination, result volume, or what the feed entries look like.

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 dense sentences with zero filler; the ordering and filter surface come first and the use-case framing closes it. Nothing is repeated from the title or the 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 and nine parameters, the description should say something about pagination via limit/cursor and roughly what an event record contains. It covers filtering well but leaves the agent guessing about result shape and page-walking, which matters for a raw feed 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 44% across 9 parameters, so the description has to carry weight and does explain name, person, session and the cross-field search semantics. It leaves limit, cursor, eventId and environment entirely to the schema, and does not say how the filters combine or which take precedence.

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 raw event feed'), its ordering ('newest first'), and its filtering surface, which lets an agent separate it from the aggregate-style siblings like list_event_names. It never names a sibling tool explicitly, so the differentiation is implied rather than stated.

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 line 'the tool that answers did my integration actually send anything' gives a concrete diagnostic scenario for choosing this tool. There is no when-not guidance or explicit pointer to alternatives such as list_event_names or get_person, so an agent still has to infer the boundaries.

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 this a safe, idempotent read, so the description's job is to add scope detail — and it does, stating that archived flags are excluded unless includeArchived is true, which is a real filtering behavior not visible in annotations. It also discloses the shape of each returned item, though it says nothing about ordering or result size.

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, no filler, with the returned-content summary placed first and the important exclusion rule second. Every sentence carries information an 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 no output schema, the description usefully previews what each flag record contains and explains the archived-flag default, covering the main behavioral questions for a read-only list tool. Only minor gaps remain, such as pagination or ordering behavior for large flag sets.

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 67%: app and environment are documented in the schema, but includeArchived has no schema description. The description supplies the missing default semantics for includeArchived, but contributes nothing about the app or environment parameters beyond what the schema already explains.

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 (feature flags) and enumerates what each entry carries — per-environment enablement, rollout percentage, targeting rules, variants — which clearly separates it from sibling tools like upsert_flag or get_app. The verb 'list' is only implied by the title rather than stated in the description itself, keeping it just 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 guidance on when to choose this over list_apps, get_app, or upsert_flag, nor any prerequisite or exclusion statement beyond the archived-filter note. The agent must infer usage from the resource name alone.

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 read-only, idempotent, non-destructive, open-world behavior, so the bar is lower. The description adds real value by disclosing the returned structure with no output schema present: per-funnel ordered steps, conversion window in hours, and a stable identifier. It does not cover ordering, pagination, or behavior when a funnel has zero steps.

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 the resource and its contents. The second sentence on stable identifiers is mildly redundant with 'each with its ordered steps' but plausibly clarifies that ids are reusable, so it mostly 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 one-parameter read tool with no output schema, the description adequately conveys the return contents, which is the main missing piece an agent would otherwise lack. Only routing guidance versus get_funnel_results and create_funnel is absent.

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 app parameter is fully documented in the schema as an application id or orgSlug/appSlug. The description only alludes to it with 'for an application', adding nothing 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 clearly states the resource returned (saved funnels for an application) and its shape (ordered steps, conversion window, stable identifier). It never uses an explicit verb like 'list', and it does not distinguish this from siblings such as get_funnel_results or create_funnel, leaving the agent to infer that this returns definitions rather than results.

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 use this tool, when not to, or which alternative to pick when the agent wants funnel performance data versus funnel definitions. The only routing hint is indirect, in the schema description that references list_apps.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds two pieces of useful context beyond that: results are returned newest first, and an 'open' incident means a rule is currently firing for the selected environment. It says nothing about pagination, default limit, or result shape.

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

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

Two short sentences with no filler, ordering and the key semantic clarification given up front. Every clause carries 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 read-only listing tool with no output schema and annotations covering safety, the description covers purpose, ordering, and the meaning of the status values that matter most. It stops short of describing pagination or the default page size implied by the undocumented 'limit' parameter.

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 50%: 'app' and 'environment' are documented in the schema, while 'limit' and 'status' are not. The description only reiterates status filtering and does not clarify what 'all' means or what acknowledged versus resolved signify, so it adds marginal value over the structured fields.

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 (alert incidents), the scoping dimension (an application), the ordering (newest first), and the filter (status), which is enough to separate it from list_errors or get_error. The verb 'list' is only implied via the title rather than stated in the sentence, keeping it just 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 explicit guidance on when to choose this over sibling read tools such as list_errors, get_error, or ask_saaspromax, and no prerequisites or exclusions are stated. The sentence about what an open incident means explains a concept rather than when to invoke the 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description reinforces that with 'Read-only: nothing is ever changed in Meta.' It also adds useful unit conventions for amounts and rates, but does not discuss auth requirements, rate limits, pagination, or ordering, so it adds only moderate behavioral context.

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

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

The description is front-loaded with the core action and then efficiently lists the returned fields, unit conventions, and read-only behavior. It is dense but largely earns its length because there is no output schema to document the return values.

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 does substantial work by enumerating the returned ad metrics, units, and read-only nature. It is nearly complete for calling the tool, though it omits details such as result ordering or pagination behavior.

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 all four parameters including the range enum are documented in the input schema. The description itself adds no parameter-specific meaning, so the baseline of 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 clearly states that this tool lists every Meta ad and enumerates the ad-level metrics returned, so an agent can understand the core operation. It does not explicitly distinguish itself from sibling tools such as get_meta_ads_overview or get_meta_ads_breakdowns, which keeps it 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?

Usage is implied by 'Every Meta ad with...' but the description gives no explicit guidance on when to choose this tool over alternatives like get_meta_ads_overview, get_meta_ads_breakdowns, or list_meta_ads_issues. It is minimally adequate but lacks routing 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/idempotent/destructive=false, so the "nothing is ever changed in Meta" sentence is reinforcement rather than new information. The genuinely additive disclosures are the ordering guarantee ("most urgent first") and the unit conventions (amounts in hundredths of the ad account currency, rates as fractions), which the 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?

One front-loaded sentence establishes the question being answered, then the issue list, then the unit and safety notes. The long enumeration is dense but every clause names a distinct detectable issue, so it earns its length; the unit/read-only tail could have been tightened.

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 by enumerating issue categories plus amount/rate encoding, which is what an agent needs to interpret results. It stops short of describing result shape or volume (per-ad rows? grouped?), a minor residual gap for a 4-parameter diagnostic 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 description coverage is 100% – app, range, source, and environment are all documented in the schema, including the range enum semantics and the default Meta ad account. The description adds nothing parameter-specific (e.g., how range interacts with issue detection), 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?

Opens with a specific framing ("What needs attention in a Meta ad account") and enumerates the exact issue classes it surfaces: rejected/limited ads, stuck review, learning-limited ad sets, excluded placements spending, spend without clicks, fatigue, under-delivery, pixel signal, bot-like visits. This clearly separates it from metric-oriented siblings like get_meta_ads_overview, get_meta_ads_breakdowns, and list_meta_ads without needing to name them.

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 use case (account health triage, ordered by urgency) is strongly implied by the content, but the description never states when to pick this over get_meta_ads_overview or list_meta_ads, and gives no exclusions or prerequisites. An agent can infer the intent but must reason about alternatives itself.

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 declare this as a read-only, idempotent, open-world operation, so safety behavior is covered. The description adds useful context about the returned fields (kind, unit, last-seen time), but it does not mention pagination, filtering behavior, or result ordering.

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 a single efficient sentence that front-loads the resource and packs the returned fields without waste. Every clause contributes directly to understanding what the tool returns.

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 needs to carry the return-value burden, and it does mention the key fields returned. However, it omits pagination, filtering semantics for limit/search, and when to choose this over get_metric_series, leaving meaningful gaps for a four-parameter list 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 50%, with the app and environment parameters documented but limit and search left undescribed. The description does not compensate by explaining what limit or search do or how they affect the returned metric list.

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 as metric names reported by an application and lists the metadata returned: kind, unit, and last-seen time. It implicitly contrasts with series-level tools like get_metric_series by focusing on names and definitions, but it does not explicitly name or differentiate from that sibling.

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 guidance on when to use this tool versus alternatives such as get_metric_series or list_event_names. The description implies discovery usage by saying it returns metric names, but no exclusions, prerequisites, or alternative routing are stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description adds genuinely non-obvious behavior — result scope is determined by the credential type and OAuth connections are pinned to the consent-time organization. It stops short of disclosing ordering, pagination, or error behavior for large org sets.

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, then the credential-dependent scoping rules. No filler or restatement of the title.

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 at a high level (organizations plus the acting role). It is sufficient to call correctly, though it omits whether the list is paginated or ordered.

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 the description correctly implies a parameterless call — nothing is expected of the caller. Baseline 4 applies since there is no parameter surface to document.

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 ('List the organizations this access token can reach') and adds the payload content ('with the role it acts as in each'). No sibling tool operates on organizations, so there is no ambiguity to resolve against the surrounding list_* 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?

The token-type breakdown (personal vs. organization vs. OAuth) tells the agent exactly what result set to expect in each auth context, which is effectively the 'when you get what' guidance. It does not name alternatives or say when not to call it, but there is no plausible alternative for this resource.

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 flag destructiveHint=true and openWorldHint=true; the description adds genuinely new behavioral context a schema cannot express — the output is a short-lived approval URL bound to the member's fresh passkey, the tool is a gate rather than an executor, and the approval must come from the human. No contradiction with destructiveHint (the approval leads to a destructive action), but the garbled phrase 'when its execution is approval' muddies the trigger condition slightly.

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 purpose then the return value then the guardrails — every sentence carries weight. The clause 'when its execution is approval' is awkward and hard to parse, costing a point on readability.

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

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

For a 7-parameter, nested-object tool with no output schema, the description does the important work: names the prerequisite call, describes the return artifact (approval URL), and states the safety contract. Remaining gaps (file size/encoding, environment semantics) are already documented in the schema, so nothing essential 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 86%, so the schema already carries most parameter meaning. The description only reinforces that inputs must be the exact fields from the command schema and must not be altered post-approval; it says nothing extra about org, app, environment, or the files object beyond what the schema states. 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 and resource ('prepare an exact application or organization action') and adds two clarifying facts agents care about: it returns a short-lived approval URL for the member's passkey and does NOT execute. This implicitly separates it from the sibling execute_command, though it never names that sibling.

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 precondition ('after reading its command schema', i.e. get_command_schema first) and explicit prohibitions: never approve on behalf of the human, never change approved inputs, never request secrets in chat. It lacks an explicit 'use execute_command when you actually want execution' routing sentence, so the alternative is only implied by 'It does not execute the action'.

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, idempotentHint, destructiveHint=false), but the description adds genuinely non-obvious context: read-only POST queries are permitted here, and membership, scope, module and PII permissions still gate execution. It does not describe error or failure behavior for unauthorized operations, which would complete the picture.

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

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

Four tight sentences, each carrying distinct information: what it does, where the operation comes from, which parameters to supply, the POST caveat, and the permission gate. The core action is front-loaded with 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?

The tool is an open-world proxy with no output schema, so the description carries the burden of explaining what comes back and how failures surface, and it does neither. Prerequisites and permission constraints are well covered, but an agent still cannot anticipate the response shape or error modes.

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

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

Schema description coverage is 100%, so the baseline is 3; each parameter is already documented in the schema. The description only reinforces the source of the values ("exact operationId and documented path, query and body parameters") without adding format or validation guidance beyond what the schema states.

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 ("Run a read-only Management API operation") and ties it to the discovery tool, so an agent can tell it apart from get_api_capabilities. It never names the sibling execute_api_operation, which is the most likely confusion point for an agent choosing a tool.

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

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

"discovered with get_api_capabilities" establishes a clear prerequisite and workflow ordering, and "read-only" plus "Includes read-only POST queries" scopes what belongs here. It stops short of explicitly routing write operations to execute_api_operation, leaving the when-not case to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: PII masking with a concrete format (a**@example.com) and the exact permission (people.pii.read) required to see unmasked values. It does not cover pagination behavior or default result size, which is why this is a 4 rather than 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 tight sentences: capability first, then the masking caveat that determines whether results are usable. No restatement of the name or title, and the trailing clause about what masking signifies resolves the obvious follow-up question without extra prose.

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

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

For an 8-parameter search tool with no output schema and 38% schema coverage, the description is missing result-shape hints, pagination semantics (cursor/limit interaction, max 100), and the environment default. It covers the highest-stakes behavior (masking/permissions) well but leaves enough gaps that an agent may need a trial call.

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 38% (only app and segment carry descriptions), so the description has to compensate. It does map meaning onto four parameters — q as free text, stage as lifecycle stage, tag, and segment — but leaves limit, cursor, and environment (including the production default) entirely undocumented in both places.

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 (Search) and resource (person profiles) and enumerates the four filter axes: free text, lifecycle stage, tag, saved segment. An agent can distinguish this from get_person (single-record fetch) by inference, but the description 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?

Usage is implied by the listed filters rather than stated: there is no 'use this when...' guidance and no explicit pointer to get_person for a known id or to list_apps for resolving the required app parameter. Adequate but leaves routing decisions to inference.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false, but the description adds real context not in any structured field: resolving clears the notification cooldown so the next occurrence is immediately reported as a regression, and the call requires write scope plus errors.write. It omits what 'ignore' does to future notifications and whether a status change is reversible.

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 the action set, followed by the non-obvious side effect and then the permission requirement. Nothing is redundant, though the permission sentence could be compressed into a clause.

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 destructive mutation with no output schema, the description covers the permission gate and one important side effect, which is decent. However it leaves the status enum ambiguity (four values, three actions) and the environment defaulting behavior unaddressed, so an agent could still mis-set status.

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

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

With only 40% schema description coverage, the description would need to carry weight, yet it only clarifies that assigneeId is optional and gives semantic meaning to resolving. It never maps the enum values open/regressed to the 'reopen' action, and app, issueId and environment are left entirely to a sparse schema.

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

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

States a specific verb set (resolve, ignore, reopen) against a specific resource (an error issue) plus an optional assignment, which separates it from read-only siblings like get_error and list_errors. It does not explicitly name a sibling alternative, 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?

The three action verbs imply when the tool applies, and the mention of write scope signals a prerequisite, but there is no explicit when-to-use versus when-not framing, no pointer to get_error/list_errors for reading, and no guidance on the destructive/irreversible aspect of resolving.

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 real context beyond the annotations: setting a stage here marks it manual and permanently blocks automatic lifecycle rules from moving it, and the call requires the write scope plus people.write. This is exactly the kind of irreversible side effect and auth requirement the agent needs. It does not restate the destructiveHint already present, which is fine.

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 filler, with the mutation scope front-loaded and the side-effect warning immediately after. Every clause carries information.

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

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

Covers the key hazard (manual stage pinning) and auth needs for a destructive, non-idempotent mutation with no output schema. However, with nested objects and 40% schema coverage it leaves open whether tags/CRM replace or merge, and what happens to omitted fields.

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 40% across 5 parameters, so the description must compensate more than it does. It names the stage, tags and CRM field groups, but says nothing about the required app/personId identifiers or whether the nested crm object merges with or replaces existing values.

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 ('Change a person's lifecycle stage, tags or CRM fields'), so an agent knows exactly what is mutated. It does not name or contrast itself with siblings like get_person or search_people, but the read/write distinction is obvious from the 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?

Usage is only implied: 'Change' signals a mutation and the required write scope hints at preconditions, but there is no explicit when-to-use/when-not or pointer to get_person for reading or search_people for finding the target id. An agent can infer the use case but gets no routing 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 flag destructiveHint=true and idempotentHint=false, and the description adds the specific consequence: omitted variants, rules and per-environment settings are wiped because the body replaces the whole definition. It also discloses the auth scopes required, 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 sentences, front-loaded with the operation, then the replace-not-patch warning, then the auth requirement. Every sentence carries distinct operational value with 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 destructive, nested-payload mutation with no output schema, the definition covers the critical risks: full replacement, data loss on omitted fields, and required scopes. It doesn't say what a successful response contains or how creation differs from replacement, but the essential calling information is present.

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

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

With only 38% schema description coverage across 8 parameters (several nested), the description compensates partially by calling out the three complex payload fields — variants, rules, environments — and the replacement semantics that govern them. It adds nothing for app, key, name, kind or description, and the kind enum is unexplained.

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 plus resource — 'Create or replace a feature flag' — which immediately distinguishes it from the read-side sibling list_flags. An agent knows exactly what the operation does 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 clear context for use: the body is a full replacement, not a patch, so callers must send the complete definition. It also names the required authorization (write scope and flags.write). It stops short of naming an alternative for partial updates, but no such sibling exists in this toolset.

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