solidworks_cam

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

Annotations already flag destructiveHint=true and readOnlyHint=false. The description adds only that fields fall back to module defaults and that units follow a convention (SI unless a unit field exists). It does not disclose that operations like save_cam_data or set_* modify CAM data, nor does it mention side effects, prerequisites, or reversibility. It adds minimal context beyond the annotations, leaving the destructive nature unelaborated.

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 a single dense sentence listing 19 operations, which is necessary but could be better structured (e.g., bullet points or grouping). It front-loads the dispatcher concept and mentions the schema, defaults, and units. It is not excessively verbose given the scope, but the run-on nature and lack of paragraph breaks reduce clarity.

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 tool with 19 operations and many parameters, the description is severely incomplete. It does not explain what each operation accomplishes, prerequisites, side effects, or workflow order. It relies on the input schema for field details, but the schema is also incomplete. The output schema exists, so return values are covered, but the operational semantics are entirely missing, making it hard for an agent to choose and invoke the right operation.

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 description coverage is 0%, meaning the description provides no parameter details. It merely says each operation has a typed field set (see the input schema) and mentions unit conventions. The schema itself is sparse for many parameters (e.g., target_operation, techdb_id have no descriptions). The description does not compensate for this lack, leaving an agent to infer parameter meaning from field names alone.

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 that the tool dispatches on payload.operation to specific handlers and lists all 19 operations. This conveys a specific, broad CAM capability set that distinguishes it from siblings like solidworks_cam_connect or solidworks_cam_status. However, it doesn't explicitly say 'use this for all CAM operations' or contrast with those siblings, so it stops short of a 5.

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?

No guidance is given on when to use this tool versus alternatives. It does not mention any other tool or provide selection criteria. The operation list implies it's for those operations, but there is no explicit 'use this when you need to...' or exclusion of other tools. An agent must infer the scope from the list alone.

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