Search Visualizations

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real behavioral context beyond that by defining the empty/null-query fallback ('lists all') and the space-scoping default. It doesn't mention result limits or pagination, but that is plausibly handled by the output schema.

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?

Three short sentences, all front-loaded and all load-bearing: what is searched, the empty-query behavior, and the space scope. No filler or restatement of the name.

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?

With an output schema present, return values need not be described, and both parameters plus the null-query case are covered. The only gap is routing guidance among the 21 siblings, which would make selection faster but isn't required to invoke the tool correctly.

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 0%, so the description carries the burden and does compensate: it explains that `query` matches on title and that null means list everything, and that `space` targets a Kibana space by id with the default space as fallback. Neither parameter's accepted format is elaborated further, but the meaning of both defaults is unambiguous.

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 and resource ('Search library visualizations ... by title') and anchors the object type by referencing create_visualization, which separates it from the dashboard and data-view siblings. It also specifies the search key (title), so the agent knows this is a lookup, not a fetch-by-id like get_visualization.

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?

'Empty query lists all' tells the agent that omitting the query is a valid enumeration path, which is genuine usage guidance. However, it never contrasts this tool with get_visualization or the other search_* siblings, so the when-to-use-vs-alternative decision is left to inference.

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