mogut_search_tools

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

With no annotations, the description carries the full burden of behavioral disclosure. It does reveal a non-obvious trait: the search covers tools that are not loaded or not implemented yet, which informs the agent about scope beyond the visible tool list. However, it says nothing about the return format, whether the search is case-sensitive, or any ordering or filtering behavior. Minimal behavioral context is provided, though enough to understand the main capability.

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 clean, front-loaded sentence that states the action, the scope, and the search criteria. Every clause adds value and there is no padding or redundancy. Efficiently sized for an API description of a straightforward search tool.

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 is simple—one query parameter, no nested objects, and no output schema. The description fully covers the tool's purpose, scope ('whole catalog'), and search dimensions, which is sufficient for an agent to decide when to call it and what to pass. The lack of an explicit statement about the returned format is a minor gap but does not block correct invocation given the tool's obvious search-and-return role.

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 100% of parameters with a clear description for 'query' ('search term', with examples). The tool description goes beyond the schema by stating which attributes of tools are searched (name, description, profile), giving the agent a fuller understanding of what the query can match. This adds meaningful context beyond the schema's simple 'search term' label.

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 ('Searches'), a clear resource ('the whole tool catalog'), and an explicit attribute ('including tools that are not loaded or not implemented yet'). It also specifies the searchable fields (name, description, profile), which distinguishes it from sibling tools that handle status, setup, discovery of profiles/sources, or metric explanation. An agent can understand the tool's function without any ambiguity.

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 conveys strong context for when to use the tool: whenever an agent needs to locate a tool within the catalog, including unloaded or unimplemented ones. It doesn't explicitly name exclusions or alternatives among the sibling tools, but the contrast is implicit since siblings target specific operations rather than a catalog-wide search. This is clear enough for typical selection.

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