Search Capacities Content

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

With no annotations, the description must carry behavior, and it does disclose meaningful traits: results may include semantically related objects, they appear after title matches under a 'Related by meaning' label, and limit caps the combined list. It does not state that the tool is read-only, how permission or account state affects semantic results beyond a conditional, or anything about ordering within the title-match group.

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?

Four short sentences, front-loaded with the core action, then behavior, then parameter notes. No filler or repetition. Slight density in packing both result-group behavior and the limit interaction into consecutive sentences, 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?

No output schema exists, and the description compensates by describing the shape of results: title matches plus an optional labeled 'Related by meaning' section. Combined with the limit and scoping notes, an agent can call this correctly. The missing piece is the absence of read-only/mutation expectations, which matters given no annotations.

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 all three parameters are already documented, establishing a baseline of 3. The description adds real meaning for limit ('caps the combined list', i.e., across both result groups) but restates the schema for query and structureIds. Net value above the schema is modest.

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 first sentence names a specific verb and resource with scope: 'Search Capacities objects in your space by title.' That distinguishes it from generic retrieval, and the semantic-search sentence clarifies the match mode. It stops short of naming or contrasting with the sibling find_objects, which an agent could reasonably confuse with this tool.

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 through the conditional semantic-search clause and the optional structureIds scoping, which hints at when to narrow results. However, it never states when to prefer this over find_objects or get_object, and gives no exclusion guidance. Usage is inferable but not directed.

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