Agentic Finance Graph

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 behavior: the result is bounded to 25 newest payments, includes counterparties, and unranked ids return not-found because an agent with no payment history has no record. That error semantics is valuable context beyond the annotations.

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

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

Two tightly packed sentences with the payload contents front-loaded and the failure condition second. No filler, though the phrasing ('sell or show') is slightly ornate for the information conveyed.

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 reasonably: rank, evidence, bindings, and 25 newest payments with counterparties. The only gap is a named alternative for retrieving a paid/fuller statement, which would round out the routing picture.

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

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

Schema description coverage is 100% and the single 'id' parameter is documented as accepting token id, slug, or wallet address. The description adds nothing about the id 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 description names a specific resource (one ranked agent's record) and enumerates its contents: rank with evidence, bindings, and the 25 newest payments with counterparties. It is clearly not a generic lookup, but it never names a sibling (e.g., agent_statement) to distinguish itself, leaving the boundary 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 'free' and by the unranked-id error clause, suggesting a cheaper alternative exists for ranked agents, but no tool is named and no explicit when-to-use guidance is given. The agent must infer the routing 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?

Annotations already declare a safe, idempotent, closed-world read, and the description adds real semantic detail beyond them: the 3-hour window, the Ed25519-signed root, the Merkle proof, the prior-statement hash, and the notion of staleness. It does not define what 'stale' means operationally or describe rate limits, keeping it out of the top tier.

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

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

Front-loads the return contents and closes with the actionable check-before-pay rule, so the ordering is sound. The middle sentence is a dense run-on of comma-separated fields that is efficient in word count but marginally harder to parse.

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

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

With no output schema, the description correctly carries the burden of explaining return values, and it does so in detail plus a usable verification rule. Gaps remain around what constitutes 'stale' and how to actually validate the Merkle proof, but the 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 100% and the id description ('Agent token id, slug or bound wallet') is already thorough, so per the rubric the baseline is 3. The description only implies the id refers to 'one ranked agent' and adds no new parameter-level syntax or format guidance.

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 ('The latest 3-hour statement for one ranked agent') and then enumerates the exact contents: spend, routing hops, unread receipts, income, open flags, previous-statement hash, and a Merkle proof against the signed root. This is far more than a name restatement and lets an agent know precisely what class of data it will receive.

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

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

Gives an explicit trigger ('Check before you pay') and concrete refusal conditions (stale, chain_ok false, flags non-empty), which is strong when-to-use guidance. It stops short of pointing at any sibling alternative, so it doesn't fully reach the 5 tier.

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 a safe, idempotent, read-only local operation, so the bar is lower. The description still adds real behavioral context beyond them: counts-only scope, the upsell boundary to the counterparty pack, and the counting rule that a routing-hop-only address is not a payee.

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

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

Dense but front-loaded: the primary use case and its returned fields come first, then the upsell boundary and the no-address fallback. Every clause carries information, though the list of counted fields is packed into one 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 values and does so by enumerating the counts, time bounds, and exclusions. Domain terms (L7, Bazaar, binding confidence) are left undefined, but the shape of the response is clear 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 coverage is 100% and the single optional parameter already documents both accepted forms (0x address, x402 URL) plus the omit-for-top-endpoints behavior. The description largely restates that dual mode, adding no format or validation detail the schema lacks, 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 resource (payments received by one Base address or x402 URL) and the exact quantities returned (counted payments, distinct agents, L7+ agents, first/last seen, excluded hops). It also distinguishes itself from the paid 'counterparty pack' that carries the payer list, so an agent can tell the two apart without opening schemas.

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

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

Clear context for use: it is a free counts-only preview, and the full payer detail lives in the counterparty pack. It also defines the no-address fallback (top endpoints paid by the most ranked agents). It stops short of explicitly naming a sibling tool to switch to, but the selection condition 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 readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile is covered. The description adds substantive domain context beyond that by describing exactly what the returned definition contains, including negative scope ('what it excludes and what it does not claim'), which tells the agent to expect disclaimers and limits rather than raw data.

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, and the content of the returned definition is front-loaded ahead of the usage instruction. 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 single-parameter, read-only, closed-world lookup with annotations covering safety and no output schema, the description covers what the tool is, what it returns conceptually, and where ids come from. It does not say what happens with an unknown or malformed id, which is the only notable 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 100%: the single id parameter is fully documented with type and an example format ('pay.usd.total.v1'). The description only adds that ids originate from other tools, a sourcing note rather than added syntax or constraint meaning, 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?

The description names the resource precisely ('the frozen definition of a metric') and enumerates its content (what it counts, method, exclusions, non-claims), which tells an agent this is a lookup of metric semantics, not a time series like metric_history. The verb is implicit ('returns') rather than stated outright, and no sibling is named explicitly, so it falls short of a 5.

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

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

'Use the definition ids returned by the other tools' gives concrete guidance on how to obtain the required id, which is the main usage question for this tool. There is no statement of when-not to use it or how it differs from metric_history, so it is clear context without 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 declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new context: results are ordered newest first, and notably 'A detection is a shape with evidence, never a verdict,' which steers the agent away from treating findings as confirmed conclusions. It omits pagination/truncation behavior at the limit cap.

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

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

Two tight sentences, front-loaded with what a detection is and how results are ordered; no wasted exposition. The trailing fragment 'Optionally for one agent' is slightly clipped but not enough to hurt materially.

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-shape burden and does so reasonably: it enumerates detection categories, the ordering, and the evidence-not-verdict nature of results. Only pagination/limit behavior is unaddressed, a minor gap for a simple two-param 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 description coverage is 50% (agent documented, limit not), so baseline 3 applies. The description reinforces that agent is optional and scoped to one, but says nothing about the limit parameter or the 25 maximum, so it does not compensate for the coverage gap.

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

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

The description names the resource (detections) and characterizes it concretely with example anomaly shapes (drain-shaped payments, retry storms, mint bursts), plus the ordering ('newest first'). It does not explicitly contrast with siblings like since_last or metric_history, but the anomaly-feed purpose 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 implied rather than stated: 'Optionally for one agent' signals that a single-agent filter is available but non-default. There is no explicit when-to-use or when-not guidance relative to sibling tools such as since_last or metric_history.

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 description adds genuinely new behavioral context: the tool does not itself pay, it returns a URL, and payment must happen through an external x402 client via USDC on Base. This is exactly the kind of side-effect disclosure 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?

Three sentences, front-loaded with the core purpose and price/purchase model. The kind enumeration is dense but every item earns its place by disambiguating the enum; no filler text.

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

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

With no output schema, the description carries the return-value burden and does so: it states the returned URL leads to an HTTP 402 with the exact price. Combined with the kind coverage, an agent has enough to call and complete the flow 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% – id is documented in the schema, but kind is a bare 9-value enum. The description compensates by defining each kind (liveness, paygraph, drain, incidents, peer, bundle, reval, statement, counterparty) and noting the id semantics for counterparty (a receiving 0x address).

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

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

The description gives a specific verb+resource ("Price and how to buy a dated evidence pack over x402") and enumerates the 9 kinds it can quote. It is clearly distinguishable from most siblings, though it does not explain why an agent would pick this over the overlapping agent_statement or counterparty_preview tools.

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

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

It explains the downstream workflow (an x402-capable client fetches the returned URL, receives HTTP 402, retries with a signed payment), which is useful operational guidance. However, it gives no explicit when-to-use or when-not-to-use guidance relative to the sibling tools that surface similar data.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value by disclosing what is returned (ranked status, liveness L0-L9, bound wallet, float, payment totals, open incidents) and that lookup is keyed on Base deployments.

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: the lookup and its accepted keys come first, and the return payload is enumerated second. No filler, and nothing is buried.

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

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

There is no output schema, and the description compensates by enumerating the returned fields, so an agent knows both how to call it and what to expect back. The one required parameter is fully specified in the schema. 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 100% and the single query param is fully documented there, so the baseline is 3. The description's restatement of token id/slug/wallet-address forms duplicates the schema rather than adding new syntax or constraint detail.

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 (Look up) and resource (one ERC-8004 agent), scoped to Base, and distinguishes itself from the plural-list sibling ranked_agents by emphasizing a single-record lookup. An agent can tell what it 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?

The accepted identifier forms imply when the tool applies, but the description never says when to prefer it over siblings such as ranked_agents or agent_record, nor does it state any exclusions or prerequisites. Usage is implied rather than guided.

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=false, covering the safety profile. The description adds genuine behavioral context beyond that: it discloses the counting methodology, stating that routing hops and pre-registration history are excluded from payment figures, that spending is bucketed by payment day, and that value, unit and measurement time accompany each figure. It still omits coverage/rate or freshness caveats beyond 'measurement time'.

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 purpose is front-loaded in the first clause, which is good. But the remainder is a single dense semicolon-and-comma run-on listing dozens of metrics, which is hard to scan and would be far more usable as a short structured list. Every clause does name real content, so there is little waste, but the structure works against 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?

With no output schema, the description must carry the burden of saying what comes back, and it does so thoroughly, enumerating the metric families and per-chain coverage. It also names the per-figure fields (value, unit, time, definition id). It does not clarify whether figures are a single snapshot or an aggregate window beyond the spending buckets, which is a minor 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, which is the baseline-4 case. The description correctly implies a no-argument, snapshot-style call, so there is nothing further for it 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?

The description states a concrete resource: a set of headline figures for AI-agent money, each with value, unit, measurement time and definition id, and enumerates the metric families covered (payments, spending averages, income, x402 inflow, treasuries, concentration, detections, per-chain registrations). It is clear what the tool returns. It does not, however, distinguish itself from siblings like metric_history (time series) or since_last (deltas), so an agent must infer which snapshot-style tool to pick.

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 statement and no mention of alternatives. The description is purely an inventory of contents, so an agent gets no guidance on choosing this over metric_history, definition, or since_last for a given question.

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 declare readOnly, idempotent, non-destructive, closedWorld. The description adds valuable behavioral context beyond annotations: gaps are real gaps, never filled; unknown key returns similar keys and full archived list. This is useful operational detail.

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 purpose, then key behavioral traits. No wasted words, though could be slightly tighter.

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 metric history tool with no output schema, the description covers granularity, gap behavior, and error fallback. Missing: explanation of the 'range' parameter's effect, and return format details (though no output schema so some burden is on the description). Overall fairly complete.

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

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

Schema description coverage is 50%. The 'key' parameter is described in the schema itself with examples. The 'range' parameter has no description in the schema and is not mentioned in the description. Baseline 3 is appropriate since the schema partially documents parameters and the description adds some context about the archive.

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 a specific resource ('history of one measured metric from the ledger's archive') and indicates the granularity (daily points, 5-minute points for last 48h). It distinguishes itself from vague siblings, though without explicit 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?

Implied usage: when you need historical metric data. But no explicit when-to-use vs alternatives, prerequisites, or exclusions. A reader knows what it does but not necessarily when to choose it over other 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/closed-world, so the safety profile is covered. The description adds the sort order ('ledger's default order') and the free-tier cap of 25, which is useful tier context, but says nothing about return fields, pagination, or why the 'different address after registration' clause matters beyond defining the level.

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 is front-loaded with the core resource and scope, with the tier cap trailing. Nothing is padded, though the parenthetical definition is embedded awkwardly inside the main 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 read-only list tool with no output schema, the definition covers what is returned, the ordering, and the item cap, which is adequate. It remains silent on what fields an agent record contains and on pagination/tier upgrade paths, leaving gaps for an agent consuming the 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 50%: min_level is documented in the schema but limit is not. The description mentions the L7+ floor (loosely tied to min_level) and the 25 cap (tied to limit's max), but adds no syntax or default-value meaning beyond the schema, so it only marginally compensates for the gap.

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

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

The description states a specific resource (top ranked agents) with an inline definition of the L7+ threshold, so an agent knows it returns a ranked agent list. However, it never names or distinguishes itself from sibling list/search tools like find_agent or agent_record, and the verb is only implied.

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?

Only 'Free tier: up to 25' hints at a usage constraint; there is no explicit when-to-use, when-not, or alternative tool named among the many siblings. The agent must infer when ranked_agents is preferable to find_agent.

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, not open world), so the bar is lower. The description still adds real behavior: no prior sample in the window yields gap: true with no delta, and nothing is interpolated. That edge-case disclosure is exactly the kind of trait annotations cannot express.

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 return shape, then window modes, then the gap rule. Dense but every sentence earns its place, and no filler appears.

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

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

With no output schema and only two parameters, the description carries the full burden and does so well: it enumerates the returned fields and covers the missing-prior-sample case. The only shortfall is the absent routing against sibling metric 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 coverage is 50%: metric_id is documented in the schema, but window's enum values carry no per-value description there. The description compensates by defining each window mode, including the default 'sweep' meaning. The metric-key-or-definition-id note merely restates the schema's own 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 specifies the resource precisely: one measured figure plus its stored prior sample, with the exact fields returned (current, prior, delta, delta_ratio, timestamps, definition id, unit, materiality). An agent knows this is a latest-value-plus-prior comparison, not a historical series. It stops short of naming the obvious sibling metric_history, so differentiation is inferred 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 window semantics ('sweep' = previous stored sample, the default; or 24h/7d/30d) imply when each mode applies, and the gap behavior explains an edge case. However there is no explicit when-to-use guidance versus metric_history or the other metric-oriented siblings, so the agent must infer the routing.

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