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

With readOnlyHint=true already covering the safety profile, the description adds two genuinely useful behavioral facts: results are ordered newest first, and operator names are pseudonymized by policy. The latter is a real data-handling disclosure an agent could not infer from annotations or schema.

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

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

Two sentences, no filler, with the resource and ordering front-loaded and the drill-down relationship second. 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?

An output schema exists, so return-value explanation is unnecessary, and the description covers purpose, ordering, privacy handling, and the drill-down relationship. The missing element is any pointer to the available filters, which matters for a tool whose parameters are largely undocumentmented.

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

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

With schema coverage at only 60%, the description must compensate. It adds nothing about the parameters — notably 'reason' and 'limit' are undocumented in both schema and description, and nothing tells the agent that machine_id, reason, or date range can be used to narrow the drill-down.

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

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

Names a specific resource (individual downtime events) and a clear scope ('newest first'), and explicitly frames itself as a drill-down companion to downtime_pareto, distinguishing it from that sibling's aggregate view. It stops short of an explicit verb like 'list', but the retrieval intent is unmistakable.

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?

'for drill-down after downtime_pareto' states exactly when an agent should reach for this tool and positions the sibling as the entry point. It provides no exclusions or negative guidance, but the triggering context is explicit rather than implied.

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 behavioral load and does it well: default exclusion of planned maintenance, largest-first ordering, cumulative share output, and the meaning of the `vital_few` grouping. It stops short of mentioning aggregation window or empty-result behavior, so not a 5.

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

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

Two tight sentences; the primary behavior (ranked downtime with cumulative share) leads, and the one notable default (planned maintenance excluded) follows. No filler or restated field names.

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 values need not be explained, and the description supplies the default-exclusion rule and the vital_few semantics an agent needs to interpret results. Only the filter parameters' interactions (line/machine/date range together) go 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 coverate is 67% and the description touches only `include_planned` ('unless asked') and implies a top-N cutoff via vital_few. It says nothing about `top` (default 10, max 20), `line`, `machine_id`, or the date range semantics, so it adds little beyond the documented schema fields. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Downtime by reason') and the exact output shape: sorted descending with share and cumulative share. The reference to pareto/vital_few makes it unambiguous that this is an analysis tool rather than a raw event list like downtime_events.

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 one scoping rule ('Planned maintenance is excluded unless asked') which shapes when the tool is appropriate, but never contrasts it with siblings such as downtime_events or machine_oee, nor states when a Pareto view beats a plain event listing. 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 only supply readOnlyHint, so the description carries the burden and adds genuinely useful behavior: customer names and prices are masked unless server policy permits confidential data. That is a non-obvious output trait an agent must know. It omits any note on pagination/limit behavior or result size, which keeps it short of a 5.

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

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

Two sentences, front-loaded with the core filtering/sorting purpose and no filler. The opening is a fragment rather than a full sentence, but nothing is wasted.

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

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

An output schema exists, so return value structure needn't be explained, and the description covers filtering, sorting, and the data-masking caveat. The main gap is the failure to distinguish this from late_work_orders, which is the most likely selection error for an agent.

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 67%, so the schema documents most parameters including the Hebrew status enum values and ISO date formats. The description merely restates the same filter fields (status, line, product, due dates) without adding format or boundary detail, 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?

It states a specific resource (work orders) plus the filter dimensions (status, line, product, due-date range) and the sort order, which is more than a bare tautology. However, it does not differentiate itself from the sibling late_work_orders, which appears to be a closely related view an agent could easily 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?

There is no explicit when-to-use guidance and no mention of alternatives, despite a directly competing sibling (late_work_orders) existing. The filtering capabilities imply a use case but the agent is left to infer when this tool is the right choice.

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, so the safety profile is covered. The description adds genuine behavioral context beyond that: the result is sorted most-urgent-first, and the 'will they run out before a new delivery can arrive' logic explains how lead time is factored into the alert.

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

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

A single dense sentence that front-loads the core condition (at/below reorder point) and then appends the derived fields, plus a short ordering note. No filler, no repetition of the name.

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 parameters, an output schema present, and readOnlyHint set, the description needs only to orient the agent, which it does well. It slightly underspecifies scope (all materials vs. a subset, freshness of the data), but nothing essential to calling 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?

The tool takes zero parameters, so there is no parameter semantics for the description to explain; the baseline for a parameterless tool is 4. The schema is empty and fully consistent with the description's implication that the tool returns a global alert list.

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

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

The description names a specific resource (materials at or below reorder point) and states exactly what the tool reports, including the computed fields. It is unambiguous against siblings such as machine_oee or downtime_pareto, but it never explicitly distinguishes itself from adjacent supply-chain tools like late_work_orders or get_work_orders.

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

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

Usage is only implied: an agent can infer this is the tool to call when it wants reorder/exhaustion risk, and the 'most urgent first' ordering hints at triage use. There is no explicit statement of when to prefer this over siblings or when it does not apply.

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 the rest of the burden: it discloses output ordering ('most late first') and resolves the real default for as_of ('the day after the last production record'), which the schema leaves as null. It does not mention result limits or pagination behavior, which keeps it out of 5 territory.

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

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

Two dense sentences, front-loaded with the primary result set and followed by the forward-looking complement and the default. Efficient overall, though the backtick-formatted parameter references make it slightly denser 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?

For a read-only filtered query with an output schema already defining return shape, the description covers scope, ordering, and defaulting behavior adequately. The remaining gap is that result-count or truncation behavior is never mentioned.

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

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

Schema coverage is only 50% (horizon_days has no schema description), and the description compensates by explaining horizon_days as the forward-looking due-date window and by supplying the effective default for as_of that the schema omits. It adds no detail on boundaries or the unit relationship, so not a 5.

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

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

The description defines the exact result set: orders past due and incomplete, plus orders due within horizon_days that haven't started or are waiting on material. That specificity implicitly separates it from the broader get_work_orders sibling, but no sibling is named explicitly, so it falls short of the 5 bar.

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 scope definition (this is the 'late and at-risk' view rather than a general order listing), but there is no explicit statement of when to prefer this over get_work_orders or how the two complement each other. Nothing misleading, but nothing that routes the agent either.

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, so the safety profile is covered. The description adds useful behavioral context by disclosing what the listing surfaces (row counts, date coverage, masked columns), which matters for a discovery tool, but says nothing about result size or limits.

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

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

Two tight sentences: capability first, then the call-first routing cue. No filler, and the most actionable instruction is front-loaded.

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

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

With an output schema present, return-value detail need not live in the description, and for a zero-parameter read-only discovery tool nothing an agent needs is missing. The description supplies exactly the orientation cue required to start a session.

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?

There are zero parameters, so there is no parameter semantics to document; the baseline for a parameterless tool is 4. The description correctly adds no redundant parameter chatter.

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 (available tables/datasets) and even previews the return payload: row counts, date coverage, and masked columns. That framing clearly distinguishes it from data-returning siblings like search_records, get_work_orders, and scrap_summary.

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 condition: "Call this first when you do not know the data." That tells the agent when to reach for it instead of the other siblings, though it names no concrete alternative for the case where you already do know the 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=true, so safety is covered. The description still adds genuine behavioral context beyond that: the OEE formula for interpreting the number, and the non-obvious ordering rule that results are sorted worst first by machine. It does not disclose default date-range behavior when date_from/date_to are omitted.

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 written sentences with no filler; the metric definition and grouping are front-loaded before the result-ordering note. Efficient, though the parenthetical formula is the only elaboration offered.

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 values need not be explained, and the description covers metric meaning, grouping grain, and result ordering. The main gap is the behavior when all filter parameters are left at their null defaults (e.g., what time window is assumed).

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 80%, so the schema already documents line, date_from, date_to, and machine_id formats. The description only echoes the group_by options and the date scoping ('for a period'), adding no syntax or default details 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 the specific metric (OEE, with its formula spelled out as availability x performance x quality) and the resource scope, plus the grouping dimension. An agent knows exactly what is computed and at what grain, though it never distinguishes itself from siblings like production_kpis or downtime_pareto.

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 guidance is given. The description never says to prefer this over production_kpis (general KPIs) or downtime_pareto (loss breakdown), nor when each group_by choice is appropriate. Usage is only inferable from the metric 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 readOnlyHint=true, so the safety profile is covered, and the description adds a genuinely useful behavioral trait not in the structured data: results are compared against the previous period of the same length. It does not mention default/omitted date behavior or any rate/permission constraints, keeping it short of a 5.

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

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

A single dense sentence, front-loaded with 'Management summary for a period,' with no wasted words. The metric list is long but each item earns its place by scoping the result set. Slightly list-heavy but 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, and annotations cover the read-only nature. The gap is that both parameters default to null and the description never states what period is used when dates are omitted, which an agent needs to 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 description coverage is 100% and both parameters are documented in the schema, so the baseline is 3. The description adds no detail about date formatting, defaults, or what period is assumed when the nullable dates are omitted.

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 this as a rolled-up management summary spanning OEE, quality, downtime, delivery and inventory — a specific composite resource. However, it never names the overlapping siblings (machine_oee, downtime_pareto, scrap_summary, late_work_orders) to explain how it differs from them. A clear purpose, but no 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?

There is no when-to-use guidance and no mention of alternatives, despite four sibling tools covering overlapping metrics. The agent must infer on its own whether to call this composite summary or the individual metric tools. Only implied usage is present.

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, so the safety profile is covered and the description only needs to add aggregation context, which it does by naming the grouping dimensions. It does not disclose the effect of omitted date bounds (both default to null) or the default grouping, so a mutation-free but behaviorally thin addition.

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 compact sentence with the metric front-loaded and the grouping options trailing. No filler, though it is a verbless fragment rather than a fully formed instruction.

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 3-parameter read-only aggregation with an enum and documented date patterns, the description is nearly sufficient; only the null date defaults and default grouping are left unstated.

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

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

Schema description coverage is 67% and both date parameters are documented with ISO format in the schema itself. The description restates the group_by enum values, which is largely redundant with the structured enum, and adds no explanation of default behavior or how grouping changes the returned rows. Baseline 3 is appropriate.

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

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

States a specific resource (scrap quantity and scrap rate) and the dimensions over which it aggregates (reason, machine, product), which is enough to separate it from siblings like machine_oee and downtime_pareto. It never names an alternative tool, but the resource is precise and 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 phrase 'for a period' and the list of grouping options imply the usage context, but there is no explicit when-to-use/when-not guidance and no mention of how this differs from other analytics siblings such as production_kpis. Usage is left to inference.

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

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

readOnlyHint already declares this a safe read, but the description adds real behavioral detail beyond that: substring matching, case-insensitivity, and the important security exclusion that masked columns are not searched. This is meaningful context an agent cannot derive from annotations or schema.

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

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

Two tight sentences that front-load the core mechanism and then supply examples and the exclusion. Every clause earns its place with no redundancy.

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, and the description covers matching semantics and the masked-column exclusion well. Minor gaps remain around the limit and table parameters, but nothing essential for calling the tool 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 only 33% — the table parameter is documented in-schema, but query and limit have no descriptions. The description clarifies the query's matching semantics (substring, case-insensitive) and its scope (not masked columns), but says nothing about the limit or table parameters, so it only partially compensates 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 states a specific verb (free-text search) and resource (record fields) with concrete mechanics (substring, case-insensitive) and two example queries that make the scope immediately tangible. An agent can tell this apart from the analytical siblings (downtime_pareto, machine_oee) 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 'for questions like ...' examples give clear positive usage context, showing exactly the kind of exploratory lookup this tool serves. However, it never states when NOT to use it or names an alternative sibling for structured retrieval.

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