Apparent

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: spend is reported in both the ad account's own currency and USD, metric provenance is disclosed (Apple counts each download while Google's installs are whatever Google reports), and it explicitly states that suggested next steps are 'never done for the person' — a meaningful guarantee that the tool will not act.

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

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

It is front-loaded with the usage trigger, which is good, but the remainder is a single run-on sentence enumerating roughly ten disjoint capabilities. The list does earn some of its length by clarifying scope, yet phrases like 'what it brought' and the parenthetical about Google's installs make it harder to scan than a short structured breakdown would.

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 an output schema present, return-shape explanation is unnecessary, and both parameters are fully documented in the schema. Coverage of metrics, currencies, and the no-side-effects guarantee is good. Minor gap: nothing says what happens when no ad account is linked or when one platform has no data, which an agent would want before calling.

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 only two parameters, and the period parameter's full syntax (7d, 30d, 12m, explicit dates, ranges) is already documented in the schema. The description implies date-bounded reporting through 'ran when' but adds no format or defaulting detail beyond the schema, so the baseline of 3 applies.

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

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

The scope is specific: paid advertising across Apple Ads and Google Ads, with an enumeration of the data returned (campaigns, spend in two currencies, downloads/installs, cost per download, payback, changes, search terms). It is distinguishable from siblings like timeline or why_did_it_change because it names the ad-account domain explicitly, though the phrase 'use for anything about paid ads' is a use case rather than a verb+resource formulation.

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 opening clause 'Use for anything about paid ads' gives a positive trigger condition, which is genuinely helpful. However, there is no when-not guidance and no routing to alternatives, despite siblings like why_did_it_change and timeline that plausibly overlap when the question is 'why did installs move' and ads are only one contributing factor.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds real behavioral value by disclosing the return contents (plain-words narrative, key numbers, highlights) and the conditional ad-spend inclusion, but it does not say what form the output takes (markdown? sections? length) or how sources are reconciled.

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

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

A single, front-loaded sentence with every clause contributing (purpose, period, numbers, ad-spend condition, highlights). The parenthetical list is dense but not wasteful; it could be marginally clearer with a comma structure, but nothing is superfluous.

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. It enumerates content categories reasonably well, but for a synthesized report tool it leaves open the response shape, length, and how the narrative is structured — gaps an agent may notice when parsing results.

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 all three parameters are documented in the schema, so the schema carries the parameter explanation. The description only echoes 'for a period' and 'one app' without adding syntax, defaults, or source-selection semantics beyond the schema — 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 what the tool produces: a narrative report for a single app over a period, plus key numbers and highlights. The enumerated contents (sales, best days, new countries, reviews, problems, ads starting/stopping) make the purpose concrete, but it never names a sibling to contrast with, so the distinction from how_are_my_apps (portfolio-wide) and app_topic is only implicit.

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

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

Usage is implied by 'One app's story for a period' — the agent can infer this is the single-app narrative summary versus the portfolio-level how_are_my_apps. However, there is no explicit when-to-use/when-not guidance and no named alternative for agents choosing between this and app_topic or timeline.

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 readOnlyHint=true annotation covers the safety profile, and nothing in the description contradicts it. The description adds real content-level context — what each topic actually surfaces (e.g. journey includes drop-off and last action before leaving; visits includes the Mixpanel session replay id when recorded) — but says nothing about result size, rate limits, or how missing sources are handled.

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 semicolon-chained wall of text with no paragraph breaks, headers, or front-loading — the reader must parse ~15 parenthetical definitions to find anything. The content is informative but the packaging defeats scanability, and the essential fact (this is a topic dispatcher for one app) is buried at the start of a very long sentence.

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 content, and it does so per topic, which is genuinely useful. But it omits how topic interacts with metric/period/source (e.g. does 'why' require a metric? does 'period' apply to 'reviews'?), and gives no hint of result shape or volume for a tool with 5 parameters and 3 enums.

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

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

Schema coverage is 100%, so baseline would be 3, but the description goes well beyond the schema here: the topic enum's own description is only 'Which part to answer about', and the description is the sole source of meaning for all 15 values (e.g. 'sources' = store sources, recorded install sources, money by source; 'properties' = latest value per attribute). It does not, however, explain how metric, period, or source interact with specific topics.

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 does convey that this tool returns one data slice (topic) for one app, and the enumerated topic list makes the scope concrete. But there is no verb framing (fetch/return) and no differentiation from siblings that clearly overlap — 'timeline', 'why', and 'ads' topics duplicate the sibling tools timeline, why_did_it_change, and ad_campaigns, and the description never acknowledges that. The mass of detail makes the core purpose harder to grasp than it should be.

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 pick this tool over the sibling tools. With timeline, why_did_it_change, and ad_campaigns existing as separate tools while this description offers 'timeline', 'why', and 'ads' topics, an agent is left to guess which entry point to use. The topic list implies what can be asked but says nothing about selection criteria or prerequisites.

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 readOnlyHint already signals a safe read, and the description adds real context: the scope is limited to live apps, the window is fixed at 7 days, the output shape is two plain sentences per app, and ads appear only when they ran. It does not mention volume limits or what happens with many apps, but the behavioral picture is otherwise solid for a no-parameter 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?

One sentence opens with the scope ("Every live app's last 7 days") and then specifies the contents, closing with the routing hint. Every clause carries information, and nothing is padding.

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

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

With no input parameters, no output schema, and only a readOnlyHint, the description carries the burden well by describing the return content and its per-app, two-sentence format. The only gap is that it does not say how many apps or how large the response can get, which matters for a fleet-wide report.

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 schema is empty at 100% coverage, so there is nothing to misread. The description correctly implies there is nothing to filter or configure (fixed 7-day window, all live apps), which is exactly the semantics an agent needs for a parameterless call.

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 (every live app) and time window (last 7 days) and enumerates the exact contents of the report: downloads, sales/money, people/retention, and ads. It does not name a sibling tool for contrast, so it falls short of the 5 tier, but an agent can still tell it apart from list_apps or ad_campaigns because those names imply narrower answers.

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 first for a general 'how is it going'" is an explicit rule for when to reach for this tool and implies it is the entry point before deeper drill-downs. It stops short of naming the alternatives (app_story, why_did_it_change, ad_campaigns) or stating when not to use it, 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?

readOnlyHint already declares this is a safe read, so the description's added value is the disclosure of returned fields (stage, RevenueCat, ads). It says nothing about ordering, volume, or whether results are scoped to the caller's account.

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 well-formed sentence that front-loads the resource and enumerates return contents 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?

With no output schema, the description usefully enumerates the key returned fields, which is the main thing an agent needs to decide whether to call it. Selection guidance against siblings is the 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies.

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

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

States a specific verb (list) and resource (apps), plus what each entry carries: id, stage, RevenueCat status, ads flag. It does not distinguish itself from the overlapping sibling 'how_are_my_apps', so it falls short of a 5.

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

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

No indication of when to call this versus 'how_are_my_apps' or 'today'/'timeline', which also surface app-level data. An agent has to infer the choice from names 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?

readOnlyHint=true already marks this as a safe read, and the description adds real value beyond that: chronological ordering (oldest first), the fact that ads appear as starting/running/stopping with spend and revenue attached, and that unusual days carry a whyId linking out to a breakdown. It does not mention pagination or how far back 'all' reaches, but the behavioral profile is otherwise well sketched.

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 usage cue is front-loaded and the whyId pointer is a useful closer, but the middle is a single run-on enumeration of eight event types that is dense to parse. Every item is arguably informative, yet the wall-of-items formatting makes the definition heavier than it needs to be.

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

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

With an output schema present, the description need not document return values, and the readOnly annotation covers safety. Given that backing, it supplies the right residual information: what the list aggregates, its ordering, and the drill-down path to why_did_it_change. Only the absence of any hint about result volume or time span keeps it below a 5.

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

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

Schema description coverage is 100%, and the schema already enumerates period formats, source options, and app identification in detail. The description adds no parameter-level meaning; the only added semantics (the whyId chain) is about a return value rather than an input. 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?

It clearly states the resource: a period viewed as a single chronological list (oldest first) containing ad starts/stops with spend and revenue, campaign changes, releases, unusual days, best days, milestones, and review bursts. The content is specific enough for an agent to recognize this is the timeline/event-history tool rather than a metric or story tool, though the operative verb ('see a period as one list') is softer than a crisp action verb.

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

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

The opening clause gives an explicit precondition ('before explaining a chart or a change'), which tells the agent to gather context first, and the closing sentence routes full drill-down to the sibling why_did_it_change using the day's whyId. It does not, however, distinguish itself from the other siblings today, app_story, or how_are_my_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 only declare readOnlyHint, so the description carries most of the burden and does well: it discloses the comparative baseline (usual day at this same hour), the breadth of the report (people, new people, behavior, spikes, slow stretches, sales/money, live ads, causes), and that a past `date` returns a whole-day view rather than an as-of-now view. Cost, latency, and freshness limits are not mentioned.

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

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

Front-loaded with the use case, then the substance, then the two parameter rules — a sensible order. It's a single dense paragraph with minor redundancy against 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 an output schema present this doesn't need to describe return structure, and annotations already cover the read-only safety profile, so the remaining need is use-context and parameter scoping — both supplied. The gap is family-level: for a 7-tool sibling set with an adjacent 'why' tool, the description should say when this one beats the others.

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

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

Schema description coverage is 100%, so both parameters are already documented and the description's restatement of 'leave out app for every app together' and the date example adds little. The one genuine addition is that `date` renders that day the same way, clarifying the semantics of the past-day mode. 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 specifies a concrete deliverable: a current-day snapshot comparing people so far against a usual day at the same hour, plus new people, spikes, sales, ads, and drivers. That's far more than a restatement of the name. It stops short of 5 because the 'why today is busier or quieter' clause overlaps with the sibling why_did_it_change and the description never draws that line.

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

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

It gives an explicit trigger phrase ('how is it going right now / today') and explicitly tells the agent how to widen scope by omitting `app` and how to re-point at a past day with `date`. What's missing is any exclusion or named alternative — an agent deciding between this, why_did_it_change, and timeline gets no routing rule.

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?

readOnlyHint already tells the agent this is a safe read. The description's main additions are output semantics (attribution share, counted vs derived, residual, confidence, one next step) and the caveat that results are 'built from the data alone' — but most of the output-shape detail is duplicated by the existing output schema, so its net behavioral contribution 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?

The trigger is correctly front-loaded, but the body is a single sprawling sentence with stacked parentheticals that is harder to parse than needed. Several clauses (period values, source options) repeat what the schema already enumerates.

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 annotations covering safety and an output schema covering the return shape, the description supplies the missing pieces: when to reach for it, how to choose date vs period vs today, and the resolution model behind causes. Nothing crucial is absent, though the relationship to sibling tools (timeline, today) is never articulated.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds semantics beyond the schema: it explains that a range is explained as a whole then day-by-day, that 30d lists outlier days newest-first, and that 'today' compares against a usual day at this hour. Only the date/period/source enumeration is merely restated.

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 pair ('explain why a number moved') plus concrete trigger situations (spike, drop, quiet or busy day), immediately setting it apart from siblings like timeline or today. An agent reading only this line knows exactly what question this tool answers.

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 opening clause gives a clear activation condition ('use whenever someone asks why a number moved') and the description then routes between date, period and 'today'. It never names an alternative sibling or a case where a different tool should be used instead, so it stops short of a 5.

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