create_heatmap

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

With no annotations provided, the description bears full responsibility for disclosing behavior. It does this well: expected duration (21-38s), timeout behavior (returns activity_id, job keeps running), idempotent caching for identical earlier requests, and the important local-time interpretation of start_time. The absence of error-handling or quota details keeps it from a 5.

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 but well-structured: behavior first, timing details second, then parameter meanings. Some material duplicates the schema's filter_type text, which costs a little efficiency, but every sentence serves a practical purpose and the critical timeout/archive behavior is front-loaded.

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 12-parameter tool with no output schema, this description covers the workflow well: inline wait, timeout fallback, later retrieval via check_status, archive reuse, filter modes, granularity, analytic_type, and local-time semantics. It does not describe the successful inline return payload or clarify direction/threshold, but the overall invocation context is mostly complete.

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 description restates filter_type combinations and granularity defaults that already appear in the schema, and adds useful 'omit it' guidance for granularity and analytic_type. However, direction and threshold are unexplained in both schema and description, and schema coverage is only 58%. This adds some value beyond the schema but leaves significant parameter semantics to inference.

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 a specific verb and resource: 'Run a temperature heatmap and wait for the result inline.' This clearly differentiates from sibling tools like submit_heatmap (which likely returns immediately) and check_status (which collects results later). It is not a tautology and conveys the tool's core behavior.

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 tells the agent when the inline-wait model applies, what happens on timeout, and that check_status can later collect the activity_id. It also notes that duplicate requests are served from the local archive. It does not explicitly name submit_heatmap as the alternative for fully asynchronous submission, but the wait/timeout behavior strongly implies the tradeoff.

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