mrd

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable behavioral context: 'answered by platform rules without any external model' indicates determinism and no external calls, and 'Returns a short answer plus data blocks' discloses the output structure. No contradiction with 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?

The description is two sentences, front-loaded with the main purpose, followed by concrete examples and a usage note. Every sentence earns its place, with no fluff or repetition of schema information. It is highly efficient and well-structured.

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 flexible question-answering tool with a single parameter and no output schema, the description covers its scope, behavior, and output format. It also provides usage guidance. It does not enumerate limitations, but for a general tool that would be impractical. Annotations cover safety, so nothing critical 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 coverage is 100% and the parameter description includes examples. The description adds semantic context about the scope and type of questions ('selection by requirements, values of a property across a class, companies by capability and country...'), which enriches understanding but does not add syntax or format details beyond the schema. With high coverage, a baseline of 3 is appropriate.

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

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

The description states a clear purpose: 'Plain-language engineering question over the whole platform' and lists specific question types (selection by requirements, values across a class, etc.). It also explicitly distinguishes itself from structured tools by noting it is used when the question does not map cleanly onto one structured tool, which differentiates it from its siblings.

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

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

It provides explicit when-to-use guidance: 'Use when the question does not map cleanly onto one structured tool.' This clearly signals when not to use it, though it does not name specific alternative tools or provide a list of when-not cases. The criterion is clear enough for an agent to decide.

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 that the tool is read-only, idempotent, and non-destructive. The description adds meaningful behavior beyond that: pre-indexed text, page numbers, exact product matches, and one excerpt per product. No contradiction is present.

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

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

One dense sentence covers both modes, their inputs, and their outputs without wasted words. The primary 'ask a datasheet' behavior is front-loaded and the alternative is clearly separated.

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?

The two modes and their output content are described, which is helpful since there is no output schema. However, the required parameter groupings are not stated explicitly — for example, whether the single-datasheet mode needs both q and product_id, while the scan mode needs term and category.

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?

q and term already have schema descriptions, and the description reinforces the term + category relationship for the scan mode. However, product_id is undocumented in the schema and the description never explains how it selects the target datasheet, leaving some parameter semantics implicit.

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 states two distinct behaviors: asking a single product datasheet a question and getting closest excerpts with page numbers, or scanning all datasheets in a category for an exact term. It is specific about the verb and resource, but it does not explicitly position itself against sibling tools like search_datasheet_facts.

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

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

It gives clear context for when to use each mode: a question about one datasheet versus an exact-term scan across a category. It does not name alternatives or exclusions, but the two-mode structure makes the usage conditions reasonably clear.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral detail beyond that: it performs voltage-compatibility checking and transparently reports items that could not be counted due to missing vendor data. This gives the agent an honest picture of what the tool will and won't provide.

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

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

The description is two sentences with no filler. It front-loads the primary function, enumerates specific outputs, adds the important limitation about unpublished vendor data, and closes with a concrete usage example. Every sentence earns its place.

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

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

For a tool with no output schema, the description enumerates the return values well: total mass, total steady-state power, per-item data interfaces, voltage-compatibility verdicts, and excluded items. It explains the integration with sibling tools and provides a realistic usage scenario. The parameter schema is complete, so no critical information 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 input schema already documents both parameters fully, including the bus voltage supply-range check and the items array with id and qty. The description adds value by clarifying that product ids come from other tools and that bus voltage is 'your' power bus voltage, tying the parameters to the intended workflow. This goes slightly beyond the schema's plain definitions.

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 the tool's purpose: building an engineering budget for a component stack. It specifies the inputs (product ids, bus voltage) and outputs (mass, power, data interfaces, voltage verdicts, excluded items), and distinguishes itself from sibling tools by focusing on budget assembly rather than component lookup or matching.

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 gives clear guidance on when to use the tool: 'assemble and sanity-check a subsystem' with a concrete example (3-4 reaction wheels for ADCS). It also implies the ids come from other tools, which routes the agent to the correct workflow. It does not explicitly list exclusions or name sibling alternatives, but the usage context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral detail beyond that by specifying the verdict categories (fits / conflict / check / unknown) and the ask_vendor behavior that reports exactly which values are missing to decide.

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?

This is one very long, run-on sentence that compresses dozens of interface checks into a single block. The content is informative, but the lack of bullet points or paragraph separation makes it difficult to parse. It is front-loaded with the core purpose, yet the enormous checklist hurts 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?

For a complex compatibility-checking tool with no output schema, the description does a good job of explaining what is checked and what verdicts are returned, including the ask_vendor fallback. It is missing only minor details such as how quantities affect the fit check or the exact structure of the returned verdicts.

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 input schema covers 100% of the single parameter's semantics: items is described as products of the spacecraft, deployer or ground segment, and each item has an id and optional qty. The description does not add parameter-level detail, but the baseline of 3 applies because the schema already carries the load.

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

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

The description opens with a specific verb and resource: 'Check whether a set of products docks together,' followed by an exhaustive enumeration of the interface checks performed. This makes the tool's purpose unmistakable and distinguishes it from match_components, which is about finding compatible parts rather than verifying a given set.

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 intended use is implied by the purpose: call this after a set of products has been identified, likely following match_components. However, the description never explicitly says when to use this tool versus siblings, nor does it state when not to use it or suggest an alternative.

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 cover only the safety profile (readOnly, non-destructive, openWorld=false), and the description goes well beyond them: LLM-backed execution, anonymized rate limits (6/min, 30/h), deterministic matching, and specific result fields (selected.fixed, fixed_verdict, fixed_fails). This is exactly the extra behavioral context an agent needs and cannot get from 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 sentences, front-loaded with the primary action and the fallback/`fixed` path, with no filler. The parenthetical output-field list is dense but earns its place since no output schema exists.

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

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

No output schema exists, yet the description names the returned evidence fields, documents the rate limit, and explains determinism and the role of `fixed`. For a 2-parameter LLM-backed assembly tool, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: `fixed` ids stay in their subsystems, are validated against stated requirements, and surface as selected.fixed/fixed_verdict/fixed_fails. The example task for `q` also clarifies its acceptable syntax beyond the schema's generic 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?

States a specific verb+resource ('Assemble a whole spacecraft bus') and the full pipeline: planning, deterministic matching, budget computation, rationale. It also names the sibling tools (match_components, get_datasheet_digest) whose output feeds it, so an agent can place it in the workflow 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?

Explains the key usage pattern: pass `fixed` with product ids you have already chosen from match_components or get_datasheet_digest, and the rest is assembled around them. That is clear context for the main branch of use, but there is no explicit statement of when NOT to use it (e.g., when to prefer build_budget or find_data_gaps instead).

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 behavioral transparency burden. It describes what the output contains and positions the tool as a reference lookup, but it does not explicitly state read-only behavior, output format, or potential limitations/errors. It is adequate but not fully transparent.

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

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

The description is a single dense sentence that front-loads the purpose and then lists concrete content areas. Every clause contributes value, and there is no filler.

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

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

The description enumerates the return content and gives an explicit call-timing recommendation. Given that there is no output schema, this is sufficient for an agent to understand what it will receive and when to invoke the tool. It stops short of detailing exact response formatting or edge cases.

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 input schema already covers both parameters with descriptive examples (category slug, subtype slug). The description does not add parameter-level meaning, but because schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly states that this tool explains property definitions, measurement, usage, confusions, ranges, and related properties for a product category. It frames its role as a pre-spec reference, though it does not explicitly distinguish itself from sibling tools by name.

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 gives explicit usage guidance: 'Call this before interpreting specs of an unfamiliar category.' It names the context clearly but does not provide exclusions or explicitly compare against alternatives like search_datasheet_facts or get_component_specs.

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 mark the operation read-only and idempotent; the description adds substantial behavioral detail beyond that: derivation thresholds (80%/120%), same-interface/band/type constraints, the exclusion of the source product from the search, and the A/B/C grouping. It also warns that equal figures do not make a drop-in replacement and that interfaces must be confirmed with the manufacturer.

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

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

The description is dense but well organized: core purpose and method first, then returns, then when to use, then a safety caveat. Every sentence carries distinct information and none is filler.

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

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

For a complex tool with no output schema, the description explains what is returned (derived requirements, non-compared fields, groups A/B/C), when to use it, and the critical interface caveat. The schema covers all parameters, so nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds general context around deriving requirements from a product's published values and searching its class, but it does not add parameter-specific meaning beyond the schema's already complete descriptions.

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 action ('Alternatives / second sources / replacements') and a precise scope ('for ONE product'), then explains the derivation method and output groups. This clearly separates it from sibling tools such as find_suppliers or match_components without needing to open their 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?

It gives an explicit trigger: 'Use when a part has a long lead time, is discontinued or export-restricted.' It does not name alternative tools or state exclusions, so it falls just short of full 5-level routing 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?

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful behavioral context by defining what each status means, including whether the user should go to the datasheet or ask the vendor, and what fields like page/excerpt can be expected.

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

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

The description is compact and information-dense: a front-loaded purpose statement followed by a concise status legend and an audience takeaway. Every clause contributes meaning; there is no filler or repetition of the schema.

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

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

There is no output schema, so the description carries the burden of explaining return semantics, which it does by defining the statuses and indicating what source or action each corresponds to. It could be more explicit about response shape and how the optional filters interact, but it is sufficient for a straightforward read-only gap lookup.

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 0% schema description coverage, the description must compensate. It explains the meaning of the status enum values and maps the tool to product, company, or category. It does not elaborate on the integer id parameters or how filters combine, but the parameter names and enums are fairly self-explanatory.

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 states the tool answers 'what is missing for a product, a company or a category and where to get it,' then enumerates the specific gap statuses. This makes its role distinct from content-query siblings like get_datasheet_digest or search_datasheet_facts.

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

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

It gives clear context for the intended audience: 'For vendors: what to publish; for buyers: what to ask.' It does not explicitly name alternative tools or state when not to use this one, so it stops short of full when/when-not 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds behavioral value by disclosing that it returns 'how many more companies may fit because the decisive value is not published' – a non-obvious behavior that helps the agent interpret results. It also implies a fuzzy matching approach ('meet engineering requirements') without promising exact matches. No contradiction with 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?

The description is three sentences and front-loads the core purpose with examples, followed by calling instructions and return behavior. It is efficient and avoids repetition of schema details. The only minor inefficiency is that the second sentence lists both parameters and the return value in one line, but it remains clear and scannable.

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 search tool with 15 parameters (1 required) and no output schema, the description adequately covers how to invoke it (category required, others optional), the parameter alignment with match_components, and what the result looks like (companies, matching products, and a count of additional potential matches). It does not mention pagination, result limits, or ordering, but given the annotations and the fact that it's a read-only search, these are minor gaps. It is sufficiently complete for an agent to use 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%, so all parameters are individually documented. The description adds cross-referencing value by noting that requirement parameters are 'same names and units' as match_components, which aids consistency and reduces ambiguity. It also gives usage examples that illustrate how to combine parameters (e.g., 'Chinese companies making star trackers better than 10 arcsec'). This goes beyond what the schema provides, earning a 4 rather than a baseline 3.

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 ('find'), a resource ('suppliers'), and a clear purpose: companies whose products meet engineering requirements in a category. It gives concrete examples ('who makes platforms for GEO') that distinguish it from sibling tools like match_components (which matches components, not companies) and find_alternatives. The purpose is unambiguous and distinct.

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 explicitly instructs to pass 'category, optional country and any requirement parameter of match_components (same names and units)', telling the agent exactly how to call it. It also explains the return value (companies with matching products and an estimate of additional companies). It does not explicitly state when not to use it or name alternative tools, but the reference to match_components implies its role in the selection flow. Clear context, though a direct comparison to siblings would be stronger.

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

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

Beyond the readOnly/idempotent annotations, the description discloses return granularity: per-value units, bounds, measurement conditions, datasheet source page, confidence, and a property dictionary grouped by interface port. It also states paging ('10 products per call') and narrowing via ids/keys. No behavioral claims contradict 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?

The content is information-dense, but it is delivered as a single long em-dash sentence that is hard to parse, and the opening 'typed layer' phrase is vague. There is no wasted information, but the structure could be clearer.

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 compensates by enumerating the fields returned and the grouping of the property dictionary. It covers pagination, filtering, and purpose, though the meaning of 'typed layer' is left implicit and no example is provided. Overall it is adequate for a read-only spec-retrieval call.

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 schema carries the parameter documentation. The description adds useful operational meaning by tying 'page with offset' to limit/offset and 'narrow with ids and keys' to the id/key filters, and it gives a concrete default page size.

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 is built around a noun phrase, 'the typed layer of a category,' rather than an explicit action like 'retrieve component specifications.' The paging/filtering details and output enumeration make the resource somewhat clear, but the opening jargon and absence of any sibling distinction keep it from being fully transparent.

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 names concrete use cases ('arbitrary comparison, budgeting or trade studies'), which tells an agent when this raw spec retrieval fits. It does not state when to prefer a sibling like get_datasheet_digest or match_components, so there are 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?

Annotations already establish readOnly, idempotent, non-destructive, non-open-world, so the safety profile is covered. The description adds useful behavioral context (confidence L0, verbatim quote verification, PDF link per fact), but doesn't state result limits, pagination, or what happens when a section is absent.

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 what the tool returns and its section taxonomy, then verification semantics, then usage and param routing. The section list is long but each item is informative; only slight trimming possible.

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 does the work of describing the returned fact shape (unit, condition, page, verbatim quote, confidence, PDF link), which is valuable. It also names where product_id comes from. The main gap is not distinguishing itself from sibling tools like get_component_specs.

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% (only the 'q' param is described in schema). The description adds meaning by saying product_id can come from match_components or a product name, which compensates for the undocumented product_id. Baseline 3 given the mixed coverage.

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 ('Facts machine-read from a product datasheet, by section') and enumerates the sections covered, so an agent knows this retrieves structured datasheet extractions. It doesn't explicitly contrast with the sibling get_component_specs or search_datasheet_facts, which is the missing 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 partial usage guidance: 'Use it for what the typed layer does not hold' and 'Pass product_id from match_components', which implies a workflow. But it never states when to prefer this over ask_datasheet or get_component_specs, nor when not to use it.

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

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

The description adds substantial behavior beyond the read-only/idempotent annotations: exact A/B/C group semantics, limits on returned items, paging via group and offset, datasheet page citations, and the note that group C lists the most often unpublished fields. It also communicates the compact response shape and how truncation behaves.

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

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

The description is dense and front-loaded with the main search concept, then covers output semantics and paging efficiently. The full category list is somewhat redundant with the schema enum, but it aids quick scanning and includes useful context for test-facilities.

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?

Given a 90-parameter tool with no output schema, the description is remarkably complete: it defines grouping, truncation rules, paging via group and offset, counts, missing-data reporting, and verdict citations. An agent has enough context to call the tool and interpret its response.

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% across 90 parameters, so the schema already defines each parameter. The description adds general guidance like 'Omit parameters you do not care about' and clarifies one category's special meaning (test-facilities items are companies), but it does not add per-parameter meaning beyond the schema.

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

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

The description gives a specific verb and resource: 'Reverse search over a typed spec layer' that returns items grouped as A, B, or C. This makes the tool's core function clearly recognizable. It does not explicitly name sibling tools to differentiate itself, though the A/B/C grouping and category list make the purpose fairly distinctive.

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 explicit: 'pass a category and engineering requirements' and 'Omit parameters you do not care about' indicate when to use the tool. However, it does not state when not to use it or point to an alternative tool such as selection_guide or find_alternatives, so an agent must infer the decision boundary.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds useful behavioral detail: one row per product, including page and quote, plus a coverage count of digested datasheets. This goes beyond annotations by describing the shape and limitations of results.

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

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

The description is compact and front-loaded: the main purpose appears first, followed by the output shape and coverage. The long list of example keys is somewhat dense but useful for disambiguating the key parameter. No wasted sentences.

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

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

Given the absence of an output schema, the description sufficiently explains return behavior: rows with product, page, quote, and coverage. It does not detail invalid-key handling or pagination, but for a read-only search tool with safety annotations, those omissions are minor and not blocking.

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 only 33% schema description coverage, the description partially compensates by explaining key as a fact key and providing concrete examples. It does not elaborate on category beyond the enum, and contains remains only documented in the schema. The added examples help, but some parameter meaning still relies on the schema or inference.

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 states that the tool searches one fact key across an entire category and reports which products state it and with which value. This gives a specific resource and scope, and the examples (connector, trl, lead_time) reinforce intent. It does not explicitly compare itself to sibling tools, but the category-wide, keyed scope is distinguishable by itself.

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

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

Usage is implied: use this tool when you need a fact key across a whole category, as opposed to a single product or open-ended question. However, it does not name alternatives such as get_datasheet_digest or ask_datasheet, nor does it state when not to use this tool. The guidance is adequate but not explicit.

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, and destructiveHint=false, so the safety profile is covered. The description adds value by detailing what the output contains (parameter ranges, side preference, counts, vendor questions, match queries) and notes the 'catalogue data only' constraint. It does not contradict annotations, and the added context is meaningful 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?

The description is front-loaded with the core purpose ('How to choose a product of one category') and then lists the specific output components. It is a single, somewhat long sentence but each clause delivers necessary information. It could be broken into bullets for readability, but it is not verbose or redundant. This earns a 4.

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 tool with no output schema, the description thoroughly explains what the agent will receive: decisive parameters with ranges, which side is better, counts per parameter, vendor questions, and ready match queries. It also covers the special 'cubesat' case. Nothing essential for calling the tool is missing; the description is complete for its purpose.

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 input schema covers the single parameter fully (100% coverage), so the baseline is 3. The description enriches the parameter semantics by providing a concrete example (category = 'cubesat' returns a list of subsystems) and explaining that category is a component class with examples. This goes beyond the schema's generic description, warranting a 4.

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 states the tool's purpose: choosing a product of a category from catalogue data. It specifies the resource (catalogue) and the action (guide selection), and the content is distinct from sibling tools like match_components or find_suppliers, which focus on different operations. The mention of 'decisive parameters', 'which side is better', and 'ready match queries' gives a precise scope.

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

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

The description implies usage for product selection guidance but does not explicitly name alternatives or conditions when not to use it. It provides clear context (from catalogue data only) but lacks exclusionary guidance or references to sibling tools. This is a 'clear context, no exclusions' scenario, matching a score of 4.

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