When Astra has to choose between near-neighbor tools, the description should give it two facts before the full schema appears: the job the tool performs, and the boundary that rules out the wrong sibling. That is the practical reading of OpenAI’s tool-search guide in OpenAI tool-search guide: tool search can defer loading all tool definitions, may reduce token usage and cost, preserve cache, and inject newly discovered tools at the end of the context window. For namespaces and MCP servers, OpenAI also says the model initially sees only the name and description, and recommends clear high-level descriptions with fewer than 10 functions per namespace.
For a CometAPI Astra integration, the routing choice is part of the tool-description design, not an afterthought. If the candidate tool inventory is already known when the request is created, hosted tool search is the clean default. If discovery depends on project state or tenant state, client-executed tool search is the better fit because the application controls the lookup step. The CometAPI Astra article in CometAPI Astra article supports the broader idea that Astra is a tool-using model and that the Responses API is the natural starting point, but that gateway support remains untested here rather than assumed.
The most useful metadata is narrow without being cryptic. It should tell Astra what to load, when to ignore a close cousin, and what kind of request would cross the boundary into a different surface. That matters because a vague description can make Astra pick the wrong tool family even when the eventual schema is correct.
Illustrative test design:
- A namespace description should state the work domain, not just the brand name inside it.
- A function description should name the decisive boundary: ETA, tracking events, or order record lookup are different jobs even when they all live in fulfillment.
- A client-side selection fixture should match the load path the app actually intends, not a hidden premise about unavailable tools.
Three near-neighbor descriptions that fit that pattern are:
fulfillment-eta: “Fulfillment tools for looking up the estimated arrival time of an existing order. Use this when the request asks for ETA, delivery date, or arrival window, but not when it needs scan history or order edits.”fulfillment-tracking: “Fulfillment tools for reading package scan events and transit history after shipment. Use this when the request asks where a parcel is in transit, but not when it only needs the ETA.”fulfillment-order: “Fulfillment tools for reading the order record itself, including customer, line-item, and status lookup. Use this when the request needs the order, not shipment timing or tracking events.”
Intended-selection fixture:
input: "Find the tool that gives the arrival estimate for order_42."
mode: hosted-tool-search
expected_surface: "fulfillment-eta"
expected_reason: "The candidate tools are already known at request creation, and the prompt asks for ETA rather than tracking events or the order record."
rejected_surfaces:
- fulfillment-tracking
- fulfillment-order
selection_rule: "Choose the tool whose description matches the exact job and boundary before loading any full schema."
All three tools operate on fulfillment data, but their descriptions separate three requested outputs: an arrival estimate, a scan history, and an order record. The ETA request can therefore be matched from the visible descriptions alone. A request for the parcel’s last scan should instead select fulfillment-tracking; a request for its line items should select fulfillment-order. It also gives the CometAPI integration a concrete decision point: if the inventory is fixed, start with hosted search; if tool discovery truly depends on runtime state, switch to client-executed search and make the application own the selection boundary.