manage_call

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

With no annotations, the description carries the full burden and does it unusually well: it discloses the 45 s wait cap and early return, the 2 s cancel grace window, repeated KeyboardInterrupts, and the important limitation that a call stuck inside one COM operation or behind a dialog only stops once that returns. It omits post-cancel state (does status still report a cancelled call, is partially-applied Inventor work rolled back?), which is the remaining behavioral gap.

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 structure is front-loaded — purpose, then per-action behavior, then args — and nearly every sentence adds behavioral information rather than restating schema. The Args block is justified because the schema lacks descriptions for action and wait_seconds, but the formatting (stray quotes, terse arg notes) is slightly ragged and the ending trails off.

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 3-parameter, zero-annotation tool with an output schema present, the description covers what an agent needs: when to poll, how long to wait, how cancellation actually behaves and where it fails to take effect. Return contents are sketched (elapsed time, dialog text, output so far, progress() line) even though the output schema would have sufficed.

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 only 33% (only 'instance' is documented), so the description must compensate — and it largely does by enumerating the action's valid values ('status' or 'cancel'), which the schema leaves as an undescribed free string, and by tying wait_seconds to the status action with a 45 s cap. It never explains the wait_seconds=0 default or the omitted-action default, so it does not fully close the gap.

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 first sentence states a specific pair of verbs (follow/poll or stop) against a specific resource (a long-running call), and disambiguates from execute_python by identifying this as the follow-up tool for calls that outlived their wait. The examples (long execute_python, Content Center scan, Inventor dialog) make the target scenario unmistakable.

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?

It clearly establishes the trigger condition — use this only after a call has outlived its wait — and routes between the two modes by explaining what each action does. It stops short of explicit exclusions, e.g. it never says how this differs from get_status or whether it applies to calls other than execute_python/Content Center scans.

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