get_ai_insights

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

With no annotations provided, the description carries full responsibility for behavior disclosure, and it excels. It details lazy generation, polling guidance, terminal states ('disabled'), transient vs. permanent errors (5xx vs. 4xx), and status vocabulary ('in_progress', 'processing', 'unavailable'). This is exemplary transparency for a tool with asynchronous behavior.

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 dense and information-rich, with every sentence contributing value. However, it is a long wall of text without visual structure (e.g., bullet points or explicit mode headings), making it slightly harder to parse for an agent. The information density justifies the length, but a more structured format would improve scannability.

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 complex multi-mode tool with no output schema, this description is exceptionally complete. It covers all modes, parameter combinations, status handling, polling behavior, prerequisites, and even relates to sibling tools. An agent has enough context to select and invoke the tool correctly across a wide range of scenarios.

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 critical semantic meaning by explaining how parameter combinations map to the three modes. It clarifies that testrun_id alone triggers run mode, while testrun_id + testcase_id triggers case mode, and neither triggers project overview. It also explains the meaning of project-only parameters like dateRange and environment, enriching the schema significantly.

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?

Clearly states the tool retrieves TestDino's AI Insights at three distinct levels (project, run, case). It enumerates exactly what each mode returns and distinguishes itself from sibling tools like get_run_details and debug_testcase. The verb ('get') plus resource ('AI insights') with explicit scope makes the purpose immediately clear.

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?

Provides explicit when-to-use guidance for each mode: project overview for 'what should we fix first?', run mode for triaging a run, case mode for fixes to a failing test. It also names sibling tools and describes when this tool serves as a poll target after get_run_details or debug_testcase report pending AI status, giving clear alternatives and prerequisites.

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