session_complete

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

With no annotations, the description carries the full burden of disclosing side effects. It clearly tells the agent that the tool stores a pattern, optionally saves the document (with save_path behavior explained as 'saveAs; omit to save in place'), and returns JSON with pattern_id and save result. It doesn't mention whether the session becomes unavailable after completion, which is an implied effect, but overall it provides strong transparency for a state-changing operation.

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 well-structured with a leading purpose sentence followed by a clear Args/Returns layout. It is concise, every sentence earns its place, and it front-loads the primary action before detailing parameters. No unnecessary fluff.

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 description is quite complete for a finalize-like tool: it covers the main effects, parameter semantics, and return value. It doesn't detail prerequisites (e.g., having an active session) or post-conditions (e.g., session invalidation), but given the tool's simplicity and the presence of an output schema (though not shown), the description provides sufficient context for an agent to use it 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 description adds meaning for every parameter, which is critical given 0% schema description coverage. It explains 'save' as saving the FreeCAD document (.FCStd), 'save_path' as the target path with 'saveAs' semantics, 'description' as what the workflow builds, and 'tags' as retrieval tags. This goes well beyond the bare schema titles, fully compensating for the schema's lack of descriptions.

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: 'Complete the active session: store the whole workflow as a reusable pattern in the pattern store... and optionally save the document to disk.' This uses a specific verb ('complete') and resource ('active session'), and mentions the foundational actions. It distinguishes from siblings like session_pause or save_pattern by focusing on session completion and pattern storage, while also referencing recall_patterns for later 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 implies when to use the tool: when completing an active session and optionally saving the document. It explicitly mentions that patterns can be recalled later with recall_patterns, which provides an alternative for retrieval. However, it doesn't explicitly state when not to use it or contrast it with similar tools like save_pattern, so it lacks explicit exclusions.

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