search_visualizations

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 details return fields ('titles, descriptions, authors, view counts, thumbnails, and direct URLs'), explains the directUrl utility, mentions the two search types ('vizzes' and 'authors'), and discloses pagination constraints ('max 100 results per request'). It does not cover rate limits or auth, but these are less critical for a public search tool.

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 four sentences, front-loaded with the core purpose, and every sentence adds value. It avoids redundancy and fluff, efficiently covering purpose, return data, type options, pagination, and use cases.

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?

Given the tool's moderate complexity and lack of an output schema, the description provides sufficient context: it names the return fields, mentions pagination, and gives usage examples. It does not describe error handling or sorting order, but these are not essential for a search tool. The description is mostly complete for an agent to select and 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?

The schema description coverage is reported as 0%, so the description must compensate. It adds meaning for 'type' by explaining 'vizzes' vs 'authors' and for pagination via 'start and count parameters (max 100 results per request).' However, it does not explain 'query' beyond a general reference or 'language' at all. The description partially compensates but leaves notable gaps.

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 clearly states the tool's function: 'Searches Tableau Public for visualizations or authors matching a query.' It specifies the resource (Tableau Public), the action (searches), and the scope (visualizations or authors). It also differentiates from sibling get_* tools by emphasizing search/discovery rather than direct retrieval.

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 context for use: 'Useful for content discovery, finding specific topics, and identifying relevant creators.' It implies when to use the tool, but it does not explicitly mention alternatives or when not to use it. Without naming a sibling like get_workbooks_list, the guidance remains somewhat general.

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