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

Annotations only cover the safety profile (not read-only, non-destructive, non-idempotent); the description adds the return value (siteId), the deliberate omission of the SDK secret key with a concrete dashboard path for retrieval, and the auth failure mode for read-only keys.

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 outcome, then the return value, then the secret-key/auth caveats. No filler and nothing repeated from structured fields.

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

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

No output schema exists, yet the description discloses what is returned (siteId) and the notable non-return (SDK secret) with the workaround, plus the permission requirement. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and the enum values and platformIdentifier format variants are documented in the schema, so the description adds no parameter-level meaning beyond it. 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 ('Register a new app/site under your Mitr workspace') plus the immediate consequence ('so it can start receiving tracked events'), which distinguishes it from read-oriented siblings like list_apps and get_app_report.

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 creation context and a prerequisite (API key with register-apps permission, read-only key errors), but no explicit routing to alternatives such as checking list_apps first or which sibling to use for edits.

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=false, destructiveHint=false, idempotentHint=false). The description adds real value beyond them: the qr:write scope requirement and the fact that each code counts separately (a billing/quota implication). It doesn't say what happens on duplicate labels, but the additions are substantive.

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, no waste, and the core action is front-loaded before the counting constraint and permission note. Every sentence 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 2-parameter creation tool with annotations covering safety and no output schema, the description plus schema is nearly sufficient. The one gap is that campaignId's format (uuid) and role are left entirely to the schema, but an agent can still call it correctly.

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

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

Schema coverage is 50%: label is documented in the schema and the description reinforces it with a placement example ('Poster, main hall'), while campaignId is only implied by 'to a campaign'. With half the parameters covered by structured fields, this lands at baseline rather than above it.

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

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

States a specific verb and resource: 'Add one printable code to a campaign', which clearly distinguishes adding a code from creating a campaign (create_qr_campaign). The label example further pins down what a 'code' is here. It doesn't name a sibling explicitly, but the resource 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?

'Each code is counted separately' implicitly tells the agent to call once per placement rather than batch, and 'Needs qr:write' signals the permission prerequisite. However, it never states when to choose this over create_qr_campaign or update_qr_campaign, leaving the routing to inference from the names.

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 is a non-read-only, non-destructive, non-idempotent operation. The description adds useful context beyond that: it returns the new funnel and requires a funnels:write API key. It does not cover error behavior or rate limits, so it is strong but not exhaustive.

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 wasted words. The purpose is front-loaded, followed immediately by the return value and permission requirement.

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

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

For a create tool with no output schema, the description covers the essential output ('returns the new funnel'), auth requirement, and step constraints. It is slightly incomplete because it does not clarify the response shape or resolve the 2+ step statement against the schema's minItems=1.

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 already documents fields such as matchType and matchValue. The description adds that steps are ordered and each is a page path or custom event, but it leaves name, siteId, and utmCampaign to the schema. It also says '2 or more' steps while the schema allows minItems=1, creating a notable semantic discrepancy.

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 a funnel. It also explains the core input shape (2+ ordered steps, each a page path or custom event) and the purpose (measuring conversion). It is clear but does not explicitly distinguish itself from siblings such as update_funnel or list_funnels.

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: use this to create a new funnel with at least two ordered steps. It gives a prerequisite (API key with funnels:write) but does not say when not to use it or explicitly route agents to update_funnel for modifications or list_funnels for viewing.

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 a non-read-only, non-destructive, non-idempotent write, and the description adds meaningful context beyond that: the required qr:write permission, a plan-based quota on active campaigns, and the fact that the new campaign is returned. It doesn't say whether the campaign is created active or as a draft, nor what error surfaces when the free-plan limit is hit.

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 short sentences, each carrying distinct information: purpose, follow-up sibling, return value, quota, and permission. Purpose is front-loaded and nothing is repeated 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?

For a two-parameter create tool with no output schema, the definition covers what it makes, what it returns, the permission needed, the plan restriction, and the natural next step. An agent has everything required to invoke it correctly in one shot.

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 carry examples and constraints (https-only pattern, 120-char name limit), so the schema does the heavy lifting. The description only restates that scanners land on the destination URL, adding no syntax or format information 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?

States a specific verb and resource ('Create a trackable QR campaign') plus the mechanism ('sends scanners to a destination URL'), which an agent can distinguish from list_qr_campaigns, get_qr_campaign, and update_qr_campaign. It also pre-empts confusion with the closely related add_qr_code by naming it as the follow-up step.

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

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

Explicitly routes the code-adding sub-task to add_qr_code and states a hard constraint ('Free plans allow one active campaign'), which is real usage guidance. It stops short of telling the agent when to reach for update_qr_campaign instead of creating a new one, so it doesn't hit full when/when-not coverage.

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

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

Beyond the annotations (write, open-world, non-idempotent, non-destructive), the description adds two genuinely useful behavioural facts: the returned endpoint omits its signing secret, and the secret comes from the dashboard. The required scope is also disclosed. No mention of rate limits or what happens to duplicate URLs.

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

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

Three short sentences, front-loaded with the action and scoping information. The fragments "which is copied from the dashboard" and "Needs webhooks:write." are terse but earn their place.

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

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

With no output schema, the description partly covers the return value (endpoint without secret) but not what the endpoint object looks like or how to retrieve the secret later. For a mutation tool that needs the schema to carry most parameter detail, this is adequate but leaves gaps around event types and duplicate endpoints.

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 isActive and eventTypes already documented in the schema. The description adds only that the URL must be HTTPS and under the caller's control, which the pattern regex largely enforces already; it says nothing about valid event type 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?

The first sentence states a concrete verb and resource: sending tracked events to an HTTPS URL the caller controls, which is what creating a webhook endpoint means. It implicitly separates itself from update_webhook/delete_webhook, though it never names a 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?

"Needs webhooks:write" gives a real prerequisite, but there is no statement of when to prefer this over update_webhook, or when not to create an endpoint at all. Usage is only implied by the tool's name.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds valuable specifics beyond that: the deletion cascades to results history, it is irreversible, and it requires two distinct permissions. These details go beyond the safety profile annotations provide, though pagination/response behavior isn't discussed (and no output schema exists).

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

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

Four short sentences, front-loaded with the irreversible destructive action, followed by permission and confirmation requirements. Every sentence earns its place 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 single-parameter tool with strong annotations and no output schema, the description covers the critical pieces: cascade scope, irreversibility, permissions, and user confirmation. The only material omission is any guidance on the funnelId parameter itself.

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 one required parameter (funnelId as a UUID) with 0% description coverage, and the description never mentions funnelId or clarifies its format. The single-parameter baseline would be higher, but with no compensating description this is a clear gap for the only input the agent must supply.

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

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

The description uses a specific verb plus resource ('Permanently delete a funnel') and immediately scopes it to 'its results history,' distinguishing it from sibling tools like update_funnel or create_funnel. An agent can tell exactly what this tool does without inspecting 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 gives clear preconditions: both funnels:write and delete permissions are required, and the agent must confirm with the user before calling. It doesn't explicitly name an alternative tool such as update_funnel for non-destructive changes, but the destructive framing implicitly routes the agent away from it.

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

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

Annotations already flag destructiveHint=true, but the description goes well beyond them: it says the deletion is permanent and irreversible, that the delivery log is destroyed alongside the endpoint, and that two scopes (webhooks:write and delete) are required. That is exactly the auth and blast-radius context an agent needs before a destructive call.

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 short clauses, front-loaded with the permanent/destructive fact, then the permissions, then the confirmation gate, then the safer alternative. 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?

Covers destructiveness, irreversibility, required authorization, required user confirmation, and the safer sibling alternative; no output schema is needed for a delete. Only the parameter-level detail is left to the schema, which is acceptable for a one-field 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% for the single endpointId parameter, and the description never mentions it or explains how to obtain it. The name is largely self-describing and format=uuid constrains it, so the gap is tolerable, but this is the one place the description adds nothing.

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 ('Permanently delete a webhook endpoint') plus the collateral scope ('and its delivery log'). This is clearly distinguishable from the sibling update_webhook, which handles pausing.

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-not: 'to pause it instead, use update_webhook with isActive false', naming the sibling and the exact parameter value. It also prescribes the human-in-the-loop gate ('Confirm with the user before calling').

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 readOnlyHint=true and openWorldHint=false, so safety behavior is covered. The description adds useful behavioral detail: it returns the configuration fields when present and returns { rule: null } when none is configured.

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. It front-loads the primary purpose and immediately follows with the important empty-state return behavior, with no wasted text.

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

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

For a zero-parameter read tool with no output schema, the description provides enough context: what is returned, which fields matter, and what happens when no rule exists. An agent can call it correctly without further information.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain. The schema is an empty object and the description appropriately does not introduce unnecessary parameter details.

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

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

The description states a specific verb and resource: retrieve the workspace's traffic-anomaly alert configuration. It also clarifies what the rule controls (spike/drop direction, threshold %, notification channel), making the tool's scope 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?

The description makes clear this applies only when an alert rule is set and explains the null case. It does not name alternatives or explicitly say when not to use it, but no sibling tool appears to serve the same retrieval purpose.

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 read-only safety and closed-world behavior. The description adds valuable context beyond annotations: the fixed 7-day window, the specific data sections included, and the fact that this is structured raw data rather than a pre-summarized 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?

The description is front-loaded with the core action and is only two sentences. The long enumeration of report sections is informative rather than wasteful, though it could be marginally more scannable if structured as a list.

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 listing the major report categories and clarifying that the output is structured for analysis. It stops short of detailing the exact response shape, but it is sufficient for an agent to know what to expect.

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 parameter siteId is documented as coming from list_apps. The description adds no additional meaning about this parameter, so the baseline score of 3 applies when the schema already handles semantics.

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 ('Fetch'), resource ('7-day analytics report'), and scope ('for one app'), and enumerates the report's contents. It is clear what the tool returns, but it does not explicitly contrast with siblings like get_workspace_overview, so sibling differentiation is only implicit via 'for one 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?

The description implies usage through its content list and notes the data is 'meant for you to analyze and summarize, not a canned report', which guides output handling. However, it gives no explicit when-to-use/when-not guidance or named alternatives for similar analytics 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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description's only added behavioral content is that the output is intended as decision context before recommending changes; it says nothing about freshness of quota data, caching, or account/permission scoping.

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 first states contents, the second states purpose. Contents are front-loaded before the recommendation guidance.

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 list the key returned fields, which is the right call. It stops short of noting units, freshness, or what happens when no plan data exists, but for a zero-arg read tool this is close to 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?

Zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The field enumeration in the description effectively describes the (empty) call's result shape rather than inputs.

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

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

Specific verb+resource with an enumeration of what it returns (plan, subscription status, quota usage, events/apps against limits). It's clearly not a mutation or a listing of apps, but it never distinguishes itself from the sibling get_workspace_overview, which an agent could plausibly confuse it with.

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?

'Useful context before recommending changes that would affect event volume or app count' gives a situational trigger, which is more than nothing. But there are no explicit when-not conditions, no named alternative (e.g. get_workspace_overview), and no prerequisites stated — the agent must infer the rest.

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 openWorldHint=false, so the safety profile is covered and the bar is lower. The description adds the result shape (entered/converted counts, conversion rate, drop-off per step), but its other claim, the 30-day default, restates the schema's own defaults, so incremental behavioral value is modest.

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 core purpose and output shape front-loaded before the default-window note. Nothing could be removed without losing information.

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

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

There is no output schema, and the description usefully enumerates the returned metrics and the default time window. What's missing is any note on ordering or shape of the per-step drop-off data across an arbitrary number of funnel steps, which matters for a variable-length 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 description coverage is 100%, so all three parameters including formats and defaults are already documented in the schema, which sets the baseline at 3. The description's 'over a date range' and 'last 30 days' add nothing the start/end descriptions don't already say.

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

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

The description opens with a specific verb and resource ('Compute conversion results for one funnel') and enumerates the returned metrics, so an agent knows exactly what it gets. It doesn't name or contrast with siblings like get_app_report or get_workspace_overview, so the differentiation comes from the schema's funnelId reference to list_funnels rather than the description itself.

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: 'for one funnel' plus the default 30-day window signal a single-funnel analytics read. There is no explicit statement of when to prefer this over other reporting tools, nor any prerequisite or exclusion (e.g., funnel must already be created via create_funnel).

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 openWorldHint, so the safety profile is covered; the description adds meaningful return-shape context (codes plus scan counts) and the analytical intent. It does not discuss missing-campaign errors, but adds more than annotations alone.

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

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

Two tight sentences with no filler; the returned data and purpose are front-loaded, followed by the id-source guidance.

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 explains what comes back (codes and per-code scan counts). It is nearly complete for a simple read tool; only error/empty-case behavior is unaddressed.

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

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

Schema coverage is 100% and the schema already documents campaignId as coming from list_qr_campaigns; the description repeats rather than extends that. Baseline 3 applies when the schema does the heavy lifting.

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

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

Specific verb+resource ('Get one QR campaign') with scope that distinguishes it from the sibling list_qr_campaigns. It also states what the response contains (codes and per-code scan counts) and the analytical purpose (which placement is working).

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

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

Explicitly tells the agent to use the id from list_qr_campaigns, giving a clear prerequisite and routing context. It does not state exclusions or when to prefer an alternative, but none is obvious for a single-resource read.

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 a safe read-only, closed-world operation, so the description's job is to add context — and it does, by disclosing the returned field set (event type, path, referrer, UTM, device/geo, custom properties) and the recency ordering. It omits pagination/truncation behavior around the 50-event cap, which is the only remaining gap.

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 core action and returned fields come first, and the sibling differentiation is deferred to the end. No redundant 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?

For a two-parameter read tool with full annotation coverage and no output schema, the description supplies enough return-content detail to call it correctly and interpret results. Only the behavior at the event cap is unaddressed.

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

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

Schema description coverage is 100%, so both siteId and limit (default 20, max 50) are already fully documented in the schema. The description adds only the implicit notion of recency ordering and does not elaborate on parameters, so baseline 3 applies.

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

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

States a specific verb ('Fetch') and resource ('most recent raw telemetry events for one app') and enumerates the fields returned. It explicitly contrasts with get_app_report's aggregated view, so an agent can distinguish it from the sibling without reading either 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?

Names the alternative (get_app_report) and the selecting condition ('spot-checking what's actually being tracked' vs 'aggregated view'). It does not state exclusions or a limit/volume caveat, but the raw-vs-aggregated routing is clear.

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 openWorldHint=false. The description adds value on top of that by disclosing the return shape (per-endpoint status breakdown, latest failure plus error) and a meaningful boundary: "Payloads are not returned." That last point prevents the agent from promising message bodies to a user. Pagination or retention windows are still unstated.

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

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

Three short sentences with zero filler. The return shape comes first, the payload exclusion second, and the situational trigger last, which is the right ordering for an agent scanning for fit.

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

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

With no output schema, the description carries the return-value burden and does so adequately: the agent knows it gets per-endpoint status counts and a latest-failure error, and that payloads are absent. Missing only minor operational detail such as how endpoints with zero deliveries appear, or whether results cover all endpoints or only active ones.

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 optional parameter deliveriesPerEndpoint carries its own description with default and bounds. The description never mentions the parameter, so it adds no meaning 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 names a specific verb and resource (show delivery counts per webhook endpoint) and enumerates exactly what is reported: counts by status (delivered, pending, failed, exhausted) plus the latest failure with its error. This clearly separates it from the sibling mutation tools create_webhook, update_webhook and delete_webhook.

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 an explicit trigger: "Use this when a user says their webhook is not receiving events." This gives the agent a concrete diagnostic entry point. It does not name an alternative tool or exclusion case, but the sibling set contains no competing read/diagnostic tool, so the guidance is effectively unambiguous.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, and the description usefully discloses the breadth of the response (a single cross-object roll-up). It does not say whether the snapshot is live or cached, nor that it is likely heavier than a scoped read, which matters for an aggregate of this 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 sentences, both earning their place: the first defines scope and contents, the second gives the calling trigger. The most actionable instruction is placed last as a natural next step 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?

With no output schema, the description must convey what comes back, and it does so by listing the object types included plus the attention-items section. Only freshness/cost of the aggregate is unaddressed, which is a minor gap for a read-only summary.

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

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

The tool takes zero parameters, so the baseline applies. The description correctly implies no filtering or scoping is possible, which is the only parameter-adjacent fact an agent needs to know.

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 (get) and resource (workspace overview) and enumerates exactly what the summary rolls up: app traffic, webhooks, QR campaigns, funnels, attention items. This clearly distinguishes it from per-object siblings like list_apps, list_funnels, or get_app_report.

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 first when the user asks how things are doing overall" gives an explicit trigger condition, which is stronger than most aggregate tools. It stops short of naming the drill-down alternatives (get_app_report, list_apps) that an agent should follow up with, so it is clear context without 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 and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the return contents (siteId, name, platform, connection status) and the workspace scoping, which matters because 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?

A single sentence that front-loads the action and scope, then lists the payload fields and the cross-tool dependency. No filler or restated title text.

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

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

With no output schema, the description carries the burden of describing the response and does so by naming all four returned fields, plus the downstream consumer of siteId. It leaves minor gaps like pagination or ordering, but 'list every app' implies a complete enumeration.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly does not invent parameter guidance where none is needed.

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 (List) and resource (apps/sites in the Mitr workspace) and enumerates the returned fields, so the tool is distinguishable from add_app and the get_* report tools. The phrase 'every app/site' also sets the unfiltered scope unambiguously.

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 parenthetical naming siteId as needed by get_app_report and get_recent_events gives a clear reason to call this first, which is real usage context. It stops short of explicit when-not-to-use guidance or naming an alternative, so it is not a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds real value by stating that it returns ALL saved funnels in the workspace along with their id, name, and step definitions, which is useful disclosure given there is no output schema. It stops short of stating result limits or pagination behavior, though 'every saved funnel' suggests a complete, unpaginated listing.

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 names the resource, its scope (workspace), and the exact returned fields, with no filler. The routing hint is embedded compactly rather than padding the text.

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

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

With no output schema and no parameters, the description carries the burden of explaining return values, and it does so by naming the id, name, and step definitions of each funnel. The remaining gap is minor: no statement about ordering or result-size limits for very large workspaces.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing in the schema for the description to compensate for. The description correctly describes a parameterless workspace-scoped listing rather than implying any filters that don't exist.

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 and resource ('List every saved conversion funnel in your Mitr workspace') and enumerates the returned fields (id, name, step definitions). It hints at the read-vs-detail sibling boundary by referencing get_funnel_results as the consumer of the ids, but it never explicitly contrasts itself with the create/update/delete funnel 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?

The parenthetical '(needed by get_funnel_results)' implies the intended workflow: call this first to obtain an id before fetching results. Beyond that implied sequencing, there is no explicit when-to-use/when-not guidance or mention of any alternative listing 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 and openWorldHint=false, so safety is covered. The description adds real value by disclosing the return payload (id, name, status, scan totals) and that plan-level QR limits are included alongside the campaigns — non-obvious behavior since limits are not campaigns. It does not mention ordering, pagination, or behavior with zero campaigns.

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 verb and resource, then the returned fields, then the secondary plan-limits note. Nothing is redundant with the title beyond the opening phrase.

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 explain return contents and it does, including the otherwise surprising plan-limits field. The only gap for a parameterless list tool is scale behavior (pagination / large accounts), which is left unaddressed.

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?

Zero parameters, so baseline is 4. The description reinforces that scope is implicit ('your QR campaigns'), signaling no filtering arguments are accepted, consistent with the empty schema.

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

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

States a specific verb and resource ('List your QR campaigns') and immediately differentiates from the sibling get_qr_campaign by noting that ids come from here. The returned fields are enumerated, so an agent knows exactly what this tool yields.

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 parenthetical 'needed by get_qr_campaign and the QR write tools' gives a clear when-to-use trigger: call this first to discover ids before any QR mutation or single-campaign lookup. No explicit exclusion of alternatives is stated, but with only one listing sibling the routing is unambiguous.

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 idempotent=true and destructive=false, so the description's real contribution is the full-replacement warning ('send every step, not only the ones that change') plus the required OAuth-style scope, which is genuinely beyond what structured fields convey. It stops short of describing response shape or consequences for omitted steps beyond the replacement note.

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 short sentences, front-loaded with the replacement semantics, then the must-send-all-steps caution, then prerequisites. 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 mutation tool with annotations covering safety and no output schema, the description carries the important behavioral burden: replacement scope, permission requirement, and id sourcing. Missing only the meaning of the optional utmCampaign 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?

Top-level schema description coverage is 0%, so the description has to compensate. It does so for funnelId (source via list_funnels) and for steps (all steps must be sent), but says nothing about utmCampaign or the name field's constraints, leaving meaningful gaps for a 4-parameter tool.

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

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

States a specific verb and resource ('Replace a funnel's name and steps') and immediately qualifies the semantics as a full replacement rather than a partial patch, which separates it from create_funnel/delete_funnel and from any incremental-edit expectation.

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 preconditions: needs funnels:write, and funnelId must come from list_funnels. It doesn't explicitly state when to choose this over create_funnel or delete_funnel, but the mutation framing makes that fairly obvious.

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

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

Annotations already declare non-read-only, non-destructive, idempotent, and closed-world, so the description earns credit for adding semantics annotations can't express: archiving halts code creation while preserving history, and it is reversible via status 'active'. The qr:write scope requirement is also stated, which is a concrete precondition an agent needs. Remaining gap is that partial-update behavior and return values are not described.

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

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

Three short sentences, front-loaded with the mutation surface, followed by the archive behavioral caveat and the auth scope. Nothing is padded; the only minor inefficiency is restating the status enum already present in 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?

For a 4-parameter mutation tool with zero schema description coverage and no output schema, the description covers intent, archive semantics and auth but leaves the identifier parameter and the constraint surface (URL scheme, name length, whether unspecified fields are left untouched) to inference. Adequate but with clear gaps an agent may hit at call time.

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 compensate; it gives semantic meaning to name (rename), destinationUrl (destination) and status transitions, but campaignId is never explained and structural constraints from the schema (1-120 char name, https-only URL, UUID format) are not restated. The enum values quoted are already in the schema, so they add no new information.

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?

Uses a specific verb and resource ('Rename a QR campaign, change its destination, or change its status') and enumerates the mutable fields, so an agent knows exactly what the tool mutates. It doesn't name siblings such as create_qr_campaign or get_qr_campaign, but the resource and mutation scope make the distinction largely self-evident.

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 enumeration of the three change types, and the archive trade-off (stops code creation, keeps history, reversible) is useful context for choosing a status. However, there is no explicit when-not guidance, no mention of alternatives, and no statement about which fields are mutually exclusive or whether a single call can combine changes.

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 the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=true), so the lower bar applies; the description usefully adds the write scope and endpointId sourcing. However, it never states the partial-update contract — whether omitted fields are preserved or whether at least one of url/eventTypes/isActive must be sent — which is the key behavioral question for a mutation with only endpointId required.

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

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

Three short sentences with zero filler, and the action plus affected fields lead. The permission note and ID-source hint follow, each earning 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 four-parameter idempotent update with no output schema, the description covers purpose, auth, and ID acquisition, which is most of what an agent needs. The remaining gap is the partial-update / minimum-field requirement, which is material but narrow.

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%, so the description is expected to compensate, and it merely echoes the parameter names (url, eventTypes, isActive) without format or semantics detail. It adds no meaning beyond the schema for URL (https-only), eventTypes (empty means none, already documented), or the all-optional constraint. Baseline-adjacent value only.

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 (change) and enumerates the mutable surface: URL, event types, and the isActive toggle. That cleanly separates it from create_webhook, delete_webhook, and get_webhook_health without needing the schema. It stops short of explicitly naming siblings, so a 4 rather than 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?

"Needs webhooks:write" states the required scope, and pointing to the dashboard or the webhook health tool tells the agent where to obtain the mandatory endpointId. There is no explicit when-not-to-use guidance or statement of what happens if no fields are supplied, so it is context without exclusions.

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