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

With no annotations provided, the description carries the full burden and does reasonably well: it discloses that this mutates data, states the write-permission prerequisite, and offers a dry_run escape hatch. It omits other behavioral traits an agent would want, such as whether annotations are additive/duplicative, how errors on an unknown metric or period are surfaced, and how severity affects the record.

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, front-loaded blocks — purpose first, then the effect/dry-run contract — with no filler sentences. 'Durable' is doing light work but the rest 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 six-parameter mutation tool with 0% schema coverage and no annotations or output schema, the definition covers write semantics and previewing but leaves the core parameter vocabulary (metric identifier, period format, severity scale) undefined, so an agent could still call it incorrectly.

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% across six parameters, so the description must compensate and largely does not. Only dry_run is explained; the formats of metric, period, note, author, and the allowed severity values remain unspecified in both schema and prose.

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 (attach) and resource (a durable finding/note/root-cause explanation) scoped to a KPI metric and recording period, which is concrete enough to separate it from read-oriented siblings like query_kpis or list_annotations. It stops short of explicitly naming the inverse sibling retract_annotation, so sibling disambiguation is only implied by the word 'durable'.

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?

Provides real operational context: write permissions must be enabled, and dry_run=true previews without committing. However it never states when this tool is the right choice versus list_annotations/retract_annotation, nor when not to use it, leaving usage largely inferred.

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

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

No annotations are provided, so the description carries the full burden. It discloses the analytical methods (parametric Z-Score vs non-parametric IQR) and their rationale, which is useful behavioral context, but does not state that this is a read-only analysis, nor mention data-freshness or volume constraints. Adequate but incomplete for an annotation-free tool.

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

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

Two sentences, front-loaded with the core action and followed by method context. Slightly diluted by qualifiers ('rigorous', 'operational risks, unexpected budget variances, or sudden performance degradation'), but overall efficient.

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?

An output schema exists, so return values need not be explained. For a three-parameter, single-required analysis tool the description covers purpose, methods, and domain scope adequately; only usage routing against siblings 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%, so all three parameters (domain, method, threshold) are already fully documented in the schema, including defaults and algorithm semantics. The description adds no parameter detail beyond what the schema provides, so the baseline of 3 applies.

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

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

Clear verb (detect) plus resource (KPI anomalies/time-series deviations), scoped to a business domain. An agent can readily distinguish this from siblings like forecast_metric or query_kpis, which do not perform anomaly classification.

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 stated goal ('identify operational risks, unexpected budget variances'), but there is no explicit when-to-use guidance or contrast with alternatives such as forecast_metric or get_company_health. The agent must infer the trigger conditions.

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

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

With no annotations provided, the description carries the full burden and does disclose meaningful behavior: the modeling approach (trend analysis and linear projection), the probabilistic method (Monte Carlo), and the result shape (upper/lower confidence bounds). It does not state that this is a read-only computation or note any cost/rate/permission constraints, which is the 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?

The first sentence is strong and front-loaded, but the second is bloated with redundant phrasing ('forward-looking' vs 'predict future trajectory', 'trend analysis and linear projection mathematical modeling'). It could convey the same method detail in roughly half the words.

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

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

An output schema exists, so return values need not be re-explained, and the description covers purpose, method, and output concept for a 3-parameter tool. What is missing is the when-to-use routing and any operational caveats, but overall it is nearly complete for invocation.

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

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

Schema description coverage is 100%, so periods, confidence_level, and metric_name are already fully documented in the schema. The description merely restates horizon and confidence-interval concepts without adding format or default guidance 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 ('Generate forward-looking time-series forecasts ... for a named KPI') and names the concrete output (Monte Carlo confidence intervals). It is clearly distinguishable from siblings like query_kpis (retrieval) and detect_kpi_anomalies (anomaly detection).

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 'forward-looking' and 'predict future trajectory' versus the historical orientation of siblings, but the description never states when to choose this over query_kpis or get_executive_summary, nor any prerequisites. Implied context only, no 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?

No annotations are provided, so the description carries the full burden. It discloses the output's shape (composite score, categorical labels, sub-component breakdown) but says nothing about permissions, cost, idempotency, or what happens when underlying data is sparse, leaving real behavioral gaps for an un-annotated tool.

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

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

The purpose is front-loaded in the first line with supporting detail after. It is slightly padded with qualifiers ('holistic', 'multi-factor'), but nothing is redundant or confusing.

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?

An output schema exists, so return values need not be re-explained, yet the description helpfully characterizes the score bands and sub-components. For a single-optional-parameter read/analysis tool this is nearly sufficient; only the lack of usage routing keeps it from being 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?

Only one optional parameter with 100% schema description coverage, so the schema already explains the domain filter and its default-to-aggregate behavior. The description adds no syntax, valid-value, or casing 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?

States a specific verb+resource: computes a composite organizational health score with a defined 0-100 scale and qualitative bands. It is distinguishable from siblings like query_kpis or get_executive_summary in tone, but never explicitly contrasts itself with them, so it stops short of a 5.

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

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

There is no when-to-use guidance and no alternatives named, despite siblings (query_kpis, get_executive_summary, detect_kpi_anomalies) that plausibly overlap. The only conditional context is for the domain parameter, which is parameter-level, not tool-selection guidance.

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

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

With no annotations, the description carries the burden and does disclose meaningful behavior: the synthesis spans Finance, Operations, and Growth, results are capped at the top 5 metrics and top 5 anomalies, and the health index is bounded 0.0-100.0 with named classification bands. It stops short of saying the operation is read-only or commenting on latency/cost for a full cross-domain computation.

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 opening sentence is well front-loaded and the paragraph on cross-domain scope earns its place. The entire 'Returns' block, however, restates the output schema field-by-field and is largely redundant given that an output schema exists, bloating the definition without adding selection value.

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

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

For a zero-parameter tool with a rich output schema and no annotations, the description supplies what an agent needs: what it produces, its scope, and its role as the aggregate briefing. The main omission is any statement of side-effect profile or execution cost, which matters because this fans out across three domains.

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 for a parameterless tool applies. No parameter semantics are claimed or missing.

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 ('Generate ... executive briefing') and explicitly defines it as a cross-domain synthesis combining health diagnostics, KPI indicators, and anomalies. That framing distinguishes it from the narrower siblings get_company_health, query_kpis, and detect_kpi_anomalies without needing to name them.

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

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

The phrases 'one-shot' and 'for leadership' imply this is the aggregate call to prefer over the individual sibling tools, and 'synthesizing health, key metrics, and anomalies' hints at the three tools it replaces. However, it never states when to use it versus those siblings or when a focused call would be better, leaving the routing to inference.

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

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

With no annotations present, the description carries the full behavioral burden. It usefully discloses default ordering (most recent first) and the existence of retracted entries that can be excluded, but says nothing about permissions/auth, pagination behavior, or the shape of returned records.

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

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

Two tight sentences with zero filler; the core capability and ordering are front-loaded, and the filtering capability follows. Nothing is repetitive or redundant.

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

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

There is no output schema and no annotations, so the description is the only source of behavioral context. It covers ordering and filtering but omits the return shape, pagination/limit semantics, and auth requirements, leaving it only minimally adequate for a listing tool.

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

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

Schema description coverage is 0%, so the description must compensate, and it partially does: it explains that results can be filtered by metric and that retracted entries are optionally included. However, the 'limit' parameter and the defaults (limit=50, include_retracted=false) are never mentioned, leaving one of three parameters unexplained.

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

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

States a specific verb and resource ('Read historical metric annotations and operator notes') plus an ordering guarantee (most recent to oldest), which is more than the name alone conveys. It implicitly contrasts with the write-oriented siblings annotate_metric and retract_annotation, but never names them, so sibling differentiation is left to inference.

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

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

The description implies when the tool is useful, i.e. pulling historical annotations filtered by a specific KPI, but gives no explicit when-to-use, when-not-to-use, or pointer to alternatives such as query_kpis or get_executive_summary. Usage must be inferred from the capability statement.

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

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

No annotations are provided, so the description carries the burden. 'Discover'/'list' strongly imply a read-only, non-mutating operation, but this is never stated outright, nor are permissions, pagination, or scope limits described. For a simple read tool this is adequate but leaves the safety profile to inference.

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

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

Two tight sentences, front-loaded with the core purpose followed by the usage cue. No filler, though the second sentence's 'Essential discovery tool for agents to...' is mildly redundant with the first.

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?

An output schema exists, so return values needn't be explained, and the description already summarizes what is listed (metrics, domains, time periods). For a one-optional-parameter discovery tool this is nearly complete; only the read-only/auth posture 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 the sole 'domain' parameter (with examples and default behavior) is fully documented in the schema. The description adds no additional parameter meaning, which is the expected baseline 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?

States a clear verb ('discover', 'list') and resource ('KPI metrics, business domains, historical time periods'), so the agent knows exactly what is returned. It distinguishes itself implicitly from query_kpis/detect_kpi_anomalies/forecast_metric by positioning itself as the metadata-inspection step, though it doesn't name those siblings explicitly.

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

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

Gives clear context: use it 'before formulating specific queries, anomaly detections, or predictive forecasts' — i.e., as a prerequisite discovery step. This routes the agent effectively, but it does not explicitly state when NOT to use it or name the alternatives by 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?

With no annotations, the description carries the full burden. It discloses the data source ('governed Postgres store') and that data is both historical and real-time, and the verbs 'Retrieve'/'Fetches' imply a read-only operation. But it omits permissions, pagination/truncation behavior, and any access-control implications of the 'governed' store.

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

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

Two sentences, front-loaded with the core action and scope. The long domain enumeration in sentence two partially duplicates the domain parameter description in the schema, which is mild redundancy but not bloat.

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?

An output schema exists and the input schema is fully described, so return values need not be explained. Still, for a multi-domain query tool the description leaves sibling differentiation and the read-safety profile implicit, which are meaningful gaps.

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

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

Schema description coverage is 100%, so all five parameters are already fully documented in the schema. The description's domain enumeration loosely maps to the 'domain' filter but adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb ('Retrieve'/'Fetches') and resource (KPIs / structured time-series metrics) with clear scope ('historical and real-time', 'governed Postgres store'). However, it never distinguishes itself from siblings like list_available_metrics, get_executive_summary, detect_kpi_anomalies, or forecast_metric, which an agent must infer from name alone.

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

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

No when-to-use or when-not-to-use guidance is provided. The description doesn't explain the relationship to detection, forecasting, or summary siblings, so an agent has no signal for choosing this tool over list_available_metrics or get_executive_summary.

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

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

With no annotations provided, the description carries the full burden and does well: it discloses that this is destructive, that it is a soft delete (retracted_at, implying recoverability), that dry_run=true previews without committing, and that a human-supplied approval_token is required. It omits return behavior and any reversibility/undo details, which keeps it from a 5.

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

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

The core facts are front-loaded, but the destructive/approval-token information is stated twice (once in the opening paragraph, again in the 'Effect' line), which is dead weight rather than reinforcement.

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 3-param mutation tool with no annotations and no output schema, the description covers the essentials an agent needs before calling: destructive semantics, a safe preview path, and an auth prerequisite. It could still say whether retraction is undoable and what the call returns.

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 0%, so the description must compensate; it explains the two non-obvious parameters (dry_run as a preview switch, approval_token as human-supplied) well beyond the bare schema. annotation_id is left unexplained, but it is self-evident from the tool's purpose.

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 ('Soft-delete an ... annotation') and clarifies the mechanism by naming the concrete effect ('stamps retracted_at'). An agent can distinguish this from annotate_metric or list_annotations without opening a schema.

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

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

The qualifier 'erroneous or outdated' gives a clear condition for when this tool applies, which is real usage guidance. It does not, however, name alternatives (e.g., annotate_metric for corrections) or state when not to retract, so it stops short of full routing guidance.

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