execute_code_async

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It precisely discloses that execution runs on a background thread, enumerates forbidden operations (GUI, selection, document objects, recompute, save), notes that print() is not captured, and instructs to use task_print() and poll via get_task_result. This is thorough and actionable.

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?

Every sentence delivers essential information. The description is front-loaded with purpose, then constraints, alternatives, output handling, and parameters. It is dense but not bloated, with clear paragraph and Args/Returns structure. No wasted words.

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?

The tool's complexity (async execution, thread safety, polling) demands thorough documentation. The description covers the what, when, constraints, output capture, and return polling mechanism. It even names the sibling get_task_result for follow-up, making it fully self-sufficient for an agent to invoke and handle results 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 single parameter 'code' has no schema description (0% coverage). The description's Args section adds only 'Background-safe Python code to execute,' but the broader description elaborates extensively on what background-safe means, including a list of forbidden operations. This compensates for the schema gap, though a slightly more detailed parameter explanation would be ideal.

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: 'Execute Python code in FreeCAD without waiting for completion.' It clearly distinguishes this from its sibling execute_code by emphasizing asynchronous execution and explicitly naming the safe alternative.

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 explicit usage conditions: 'Only for long pure OCCT/CPU computations on already-fetched shapes.' It also states when NOT to use it ('must NOT touch FreeCADGui...') and names the alternative ('use execute_code instead'). This leaves no ambiguity about when to select this tool.

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