catalog

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 that output includes 'dated indicative prices' and 'per-line rationale', which hints the pricing is non-binding, but with an output schema present most of the return-shape detail is redundant and no logging/persistence or performance behavior is disclosed.

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, front-loaded with the action and resource, with the override capability in a short trailing sentence. The output enumeration is slightly list-heavy and partly duplicates the output schema, but nothing is wasteful.

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

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

With an output schema present the description need not explain return values, and annotations cover the safety profile. The remaining burden — what the tool produces at a high level, that build_id selects a known reference build, and that choices are per-role overrides — is all covered.

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 (including the nested 'choices' map) are already documented in the schema; baseline is 3. The description's 'Override any role with choices' adds the useful nuance that choices are overrides layered on an existing build, but no role vocabulary or error behavior for unknown roles.

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 ('Composes a complete BOM for a reference build') and enumerates the concrete outputs it produces, so the agent knows it is a generative build tool rather than a reader. It does not, however, name or contrast itself with the obvious siblings view_bom or check_compatibility, leaving the boundary to inference.

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

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

The only usage guidance is 'Override any role with choices', which describes a capability rather than a when-to-use condition. Nothing tells the agent when to call build_bom instead of view_bom (reading an existing BOM) or check_compatibility, nor whether build_id must already exist.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, closed world), so the description is not burdened with that. It adds real value beyond them: the specific engineering domains checked, the fact that each check returns a reasoned verdict rather than a boolean, and the data-quality guarantee that cited numbers are corroborated attributes. It does not discuss failure modes when part_ids reference unknown parts or how an ambiguous build_id default is resolved.

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 action and the checked domains, with no filler. The domain list is dense but each item is informative; the closing sentence on corroborated attributes earns its place as a trust signal.

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 shape need not be explained, and the description supplies what the schema cannot: which constraints are evaluated and that verdicts are reasoned. For a read-only analysis tool with modest parameter complexity this is nearly complete, with the only gap being behavior on invalid or unknown part IDs.

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% — build_id's defaulting rule and project_context's ranking/logging behavior are already documented in the schema. The description says nothing about any of the three parameters, and part_ids (1–40 IDs) carries no description in either place. At this coverage level the schema does most of the work, so a baseline 3 is right.

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 verb (evaluates) and resource (a part set against a build's engineering constraints), and enumerates the concrete checks: supply windows, stall vs peak current, shaft/wheel fit, interfaces, solar chain. It implicitly separates itself from compare_parts by operating on a whole set with a reasoned verdict per check, but never names that sibling or any other, so the 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 intent (is this combination of parts buildable?) is clear from the description, but there is no explicit when-to-use, no exclusions, and no routing against compare_parts, get_part, or build_bom. The agent must infer from the sibling list which tool answers a compatibility question versus a pairwise comparison.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds genuine value with the semantics of absence ('sources did not state a value' vs 'part lacks the property'), which is essential for interpreting the comparison correctly.

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 zero waste; the core purpose is front-loaded and the absence-semantics caveat follows immediately.

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 rich annotations, full schema coverage, and an output schema, the description carries little extra burden. It covers the one thing structured fields can't easily convey — how to read missing values — making it complete for correct 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 coverage is 100%, so a, b, and project_context are already documented, including the privacy/logging note on project_context. The description adds no parameter-level detail beyond the schema, 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 and resource: 'attribute-by-attribute comparison of two catalogue parts'. This clearly separates it from single-part tools like get_part and fetch, though it doesn't explicitly name the sibling it contrasts with (e.g., check_compatibility).

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 by the verb 'comparison' — an agent can infer this is for contrasting two parts, but the description never states when to prefer it over check_compatibility or get_part, nor any prerequisites.

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

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

Annotations already establish readOnly, idempotent, non-destructive, and non-openWorld behavior, so the safety profile is covered. The description adds the useful detail that the record is 'provenance-backed' and returned as a 'citable document', but says nothing about size, pagination, or failure behavior if the id is unknown. With annotations carrying the safety burden, a 3 is appropriate.

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 short sentences with no filler; the core action ('Fetch the full provenance-backed record') is front-loaded. Slightly terse given the alias relationship, 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 detail is unnecessary, and annotations cover the safety profile; the description supplies the missing framing that this is a provenance-backed citable document and the get_part-equivalent connector shape. The only real gap is the id format, which is minor for a one-parameter read 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% for the single required 'id' parameter, but the description compensates partially by specifying the id is a 'search result id', which is meaningful semantic context beyond the bare schema type. It does not state the accepted format of that id, so the documentation remains incomplete.

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 verb and resource ('Fetch the full provenance-backed record for a search result id') and explicitly states the tool is an alias of get_part 'shaped to the search/fetch connector contract', which helps an agent distinguish it from get_part and search. It stops short of a fully crisp differentiation because 'alias of get_part' leaves the agent to infer the practical difference between the two at call time.

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 search result id' implies the tool should be used after a search, and 'Alias of get_part' hints at an alternative, but there is no explicit when-to-use/when-not guidance or statement of when to prefer this over get_part directly. Usage is inferred rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds useful context about the richness of the returned record (provenance, vendors, datasheet links), but does not disclose operational traits like authentication, rate limits, or side effects beyond what annotations 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 a single, front-loaded sentence that immediately states the core purpose and then efficiently lists the notable contents. Every clause earns its place without redundancy or 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?

Given the simple get-by-id operation, rich annotations, 100% schema coverage, and an output schema, the description is complete enough for an agent to understand what the tool returns. Missing usage guidance belongs to a separate dimension and does not make the definition incomplete here.

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 already documents both parameters and their meaning, including the ranking effect of project_context. The description does not add parameter-level detail beyond what the schema provides, so a baseline 3 is appropriate.

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

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

The description states a specific resource ('complete canonical record for one part') and enumerates what it contains, so the purpose is clear. However, it does not explicitly distinguish itself from close siblings such as get_provenance or search_parts, leaving the agent to infer the difference.

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 guidance on when to use this tool versus alternatives like search_parts or get_provenance. The phrase 'complete canonical record' implies a detailed lookup use case, but no when-to-use or when-not-to-use instruction is provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed world, so the safety profile is fully covered. The description's remaining disclosures (receipt constituents, the citation line) largely restate what the output schema already returns, and the 'omit code' default duplicates the schema's code description, so it adds only modest value beyond structured fields.

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 concept (the receipt) and followed by a short operational rule. The first sentence is list-heavy but each item is informative; no filler or restated title.

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 a full schema, annotations, and an output schema, the description only needs to convey intent and defaults, which it does. The gap is relational: it never situates this tool against get_part or the other retrieval siblings, which is the main thing an agent would still have to guess.

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 are documented in the schema itself. The description only echoes the 'omit code for all' behavior already stated in the code parameter's description and says nothing about id or project_context, 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?

The description states a specific artifact — the provenance receipt behind a stated value — and enumerates its contents (source quote, page, extraction method, sha-256, citation line), which makes the purpose concrete. It does not, however, differentiate this from siblings like get_part or search_parts, so an agent must infer the boundary 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?

There is no explicit when-to-use guidance: nothing says to call this after get_part when a citation is needed, nor when it is unnecessary. The only guidance-like sentence is 'Omit code for every attribute's receipt,' which is parameter behavior rather than usage routing.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful content-level transparency by stating the tool returns reference builds with their roles and candidate parts. It does not discuss ranking or logging, but those are captured in the parameter 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?

The description is a single sentence that front-loads the core resource, provides concrete examples, states what is returned, and ties the tool to the BOM workflow. Every phrase 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?

For a simple list tool with one optional parameter, full schema coverage, strong annotations, and an output schema, the description is complete. It tells the agent what the tool returns, what the content is, and where it fits in the larger build_bom process.

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 for the single optional parameter is 100%, so the baseline is 3. The tool description does not add parameter-specific detail; it focuses on the resource and output contents, which is sufficient given the schema already documents project_context thoroughly.

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 ('catalogue's reference builds'), enumerates examples (robot, weather station, plant waterer), and specifies the result contents ('roles and candidate parts'). It also explicitly links the tool to the build_bom workflow, distinguishing it from sibling part/category tools.

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

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

It clearly positions this tool as 'the starting point for build_bom', giving the agent an actionable context for when to invoke it. However, it does not explicitly name alternatives or exclusion scenarios, so it stops short of a 5.

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

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

Annotations already include readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds that the output includes part counts per category, which is useful behavioral context beyond 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 a single, concise sentence that delivers the essential information about what the tool returns. No wasted 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?

With an output schema and comprehensive annotations, the description adequately completes the picture. It clarifies the tool returns all categories with part counts, and the optional parameter is for ranking. Given the tool's simplicity, this is sufficient.

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 only parameter project_context has a detailed description in the schema (100% coverage), including max length and privacy note about logging. The tool description adds no additional 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 'Every category in the catalogue with its part count' clearly states the tool lists all part categories and includes a part count. It distinguishes from siblings like search_parts or get_part, though it doesn't explicitly differentiate.

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 fetching categories in the catalogue, but doesn't provide explicit context on when to use it vs alternatives. The optional project_context parameter suggests ranking use, but no explicit when-to-use guidance is given.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds the output pointer (ids for fetch) and the aliasing relationship, but says nothing about limits, ranking, or empty-result behavior beyond what the output schema provides.

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 short sentences with no filler; the purpose is front-loaded and the workflow hint follows immediately.

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 safety profile. What is missing is the query semantics and a clear rule for choosing this over search_parts, which an agent needs given the near-identical sibling.

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 single parameter 'query' has 0% schema description coverage and the description never mentions it, so there is no guidance on query syntax, whether it is natural language or keywords, or the 500-character limit's implications.

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 (search) and resource (Partsgraph demo catalogue) and notes it is an alias of search_parts shaped to the search/fetch connector contract, which meaningfully separates it from the sibling. It does not clarify how it differs from fetch or get_part beyond returning ids.

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?

'Returns result ids for fetch' implies a search-then-fetch workflow, which is useful context. However, it never says when to pick this over search_parts (the tool it aliases) or when not to use it, leaving the choice 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real value beyond that by asserting the data-quality guarantee that every returned attribute was corroborated against a manufacturer datasheet or vendor page, which tells the agent how much to trust 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?

Two tight sentences with the core action and available filters front-loaded. The provenance sentence is slightly promotional but does carry the trust information noted above, so it largely 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?

With an output schema present, return values need not be explained, and annotations handle safety. What is missing is the ranking behavior (results are ordered for the supplied project context) and the default/pagination semantics of 'limit', both central to a search 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 only 33%, so the description must compensate, and it does cover three of the six parameters (category, build, role) as filters. It adds nothing about 'limit' behavior or how 'project_context' re-ranks results beyond what the schema already says.

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 ('full-text search over ... provenance-backed part records') and names the dimensions it filters on, which separates it from get_part and compare_parts. It does not, however, distinguish itself from the sibling tool literally named 'search', leaving an ambiguity an agent must resolve elsewhere.

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?

'Filter by category, build or role' describes capability rather than when to reach for this tool instead of get_part (known part id) or compare_parts (comparison). Usage is inferable from the verb but no alternative is named and no exclusions are given.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is low. The description adds non-structured context the annotations cannot convey: this tool renders an interactive UI and only works in MCP Apps-capable clients, and it returns the same data as build_bom. It does not say what happens in a non-supporting client, keeping 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?

Two short sentences, zero filler, with the interactive-rendering constraint and the build_bom equivalence front-loaded. Every sentence carries information an agent needs.

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 no explanation, and the annotations carry the safety profile. The description covers client compatibility and data equivalence, leaving only the undocumented 'choices' parameter and the non-supporting-client fallback as minor 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?

The description adds no meaning about build_id or the nested 'choices' map beyond what the schema labels. At 50% schema description coverage, 'choices' is an undocumented nested object with no explanation of its keys or purpose anywhere, so the description fails to compensate for the gap.

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

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

States a specific verb and resource ('composes the BOM for a reference build') plus the rendering behavior ('interactive view'), and explicitly distinguishes itself from the sibling build_bom by noting it is 'Same data as build_bom' but presented as a view. An agent can select between the two without opening either 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?

Gives a clear selection condition: use this in clients that support MCP Apps, and the 'Same data as build_bom' note implies build_bom is the fallback for other clients. It stops short of stating the alternative explicitly ('use build_bom when the client lacks app support'), so it is strong but not complete.

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