qobrix_search_properties

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

With no annotations, the description carries the full burden and excels: it discloses the fast path vs. ranked mode, that boost 'Never filters out rows — only ranks them,' that results include _relevance/_matched and pagination.mode='ranked', that result_too_large triggers _refine_required, and that pages are response-cached with QOBRIX_CACHE_TTL. This is rich, actionable behavioral transparency.

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 long but extremely dense and well-structured: it opens with a clear value proposition, uses a labeled recipe, includes concrete examples, and closes with caching/error handling. Every sentence contributes operational value, and the structure makes the complexity navigable rather than overwhelming.

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 tool with 9 parameters, no output schema, and no annotations, the description is remarkably complete. It explains both execution modes, return metadata, pagination behavior, error handling (result_too_large/_refine_required), caching, and performance trade-offs of max_scan. It also points to helper tools (qobrix_search_dsl_help, qobrix_get_field_options, qobrix_get_schema) for further context.

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?

Although schema coverage is 100%, the description adds substantial semantic value beyond the schema: it explains the search/boost/limit/max_scan interplay, that page is 'Ignored when boost is set,' that expand/media cap max_scan at 100, and it provides complete examples. This goes far beyond repeating parameter names and helps the agent select the right combination.

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 opens with 'Highly relevant property search for free-language buyer demand (F1-optimized),' clearly identifying the action (search) and resource (properties) plus the unique value proposition. The two-tier recipe further clarifies its purpose, but it does not explicitly distinguish itself from sibling tools like qobrix_list_properties or qobrix_search_projects, so it lacks an explicit sibling contrast.

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 provides clear usage context: it explains when to use boost vs. plain search, advises calling qobrix_search_dsl_help before composing queries, and gives practical guidance like 'keep modest to avoid context overload.' However, it never states when NOT to use this tool or names alternatives such as qobrix_list_properties, so the when/when-not guidance is not fully explicit.

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