searchSearch the Partsgraph demo catalogue. Returns result ids for fetch. Alias of search_parts shaped to the search/fetch connector contract.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
| Name | Required | Description | Default |
|---|---|---|---|
| results | Yes |
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 description isn't required to repeat those. The description adds that it's an alias of search_parts and returns result ids, which provides useful context about the interaction with fetch. 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?
Two sentences, no fluff. Each sentence provides essential information: what it does, returns result ids for fetch, and its alias relationship.
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 tool has a simple schema (one string param), an output schema (likely describing result ids), and annotations that cover safety. The description is short but sufficient for a simple search tool. It could mention that results are ids for fetch, which it does. The only gap is not clarifying how query affects results, but given the simplicity, it's adequate.
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%, but there is only one parameter 'query' which is self-explanatory. The description mentions 'Search the catalogue' but doesn't explain the query syntax or expected format. Since the parameter is simple and the description introduces the concept of returning result ids, a baseline score 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 the tool searches the catalogue and returns result ids for fetch. It also mentions it's an alias of search_parts, which helps distinguish it from the sibling search_parts tool. However, it doesn't fully clarify the difference between 'search' and 'search_parts' beyond being an alias.
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 says it's shaped to the search/fetch connector contract, implying a specific usage pattern. It mentions returning result ids for fetch, guiding the agent to use fetch next. However, it doesn't explicitly state when not to use this tool or alternatives like search_parts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
The core tools are distinct, but fetch/search are aliases of get_part/search_parts, and view_bom duplicates build_bom data. Descriptions clarify the aliases, so agents can disambiguate, but the redundancy introduces minor confusion.
Most tools follow verb_noun (get_part, list_builds, check_compatibility). However, fetch and search are bare verbs, and fetch/get_part and search/search_parts show inconsistent verb choices for the same operation.
11 tools is well-scoped for a parts catalogue with search, BOM, and compatibility features. Each tool has a clear role, and no obvious bloat.
The surface covers search, retrieval, provenance, comparison, compatibility, and BOM generation. Minor gaps: no direct enumeration of parts by category (only counts) and no CRUD, but for a read-only demo catalogue this is acceptable.