femm_new_document

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

No annotations exist, so the description carries the full burden. It usefully discloses that the chosen physics determines which command family (mi_/ei_/hi_/ci_) becomes available, which is real behavioral context. However it says nothing about whether an open session is required, whether an unsaved current document is discarded, or what happens on failure — meaningful gaps for a creation/state-changing tool with zero annotation coverage.

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?

Two dense sentences, front-loaded with the verb and resource, followed by the physics options and the workflow chain. No filler and every clause carries routing or parameter information.

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 document-creation tool with no annotations and no output schema, the description covers the physics choice and the build sequence well but omits session semantics, the fate of any currently loaded model, and error/return behavior. Adequate to call correctly in the happy path, incomplete around state and prerequisites.

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%, so the description must compensate. It does fully document the physics parameter by enumerating all four accepted values, adding meaning the bare string schema lacks. But the session parameter (default 'main') is left entirely undefined — no hint of what a session is or how it relates to femm_session_open — so coverage is only partial.

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?

States a specific verb and resource ('Create a new empty model') and enumerates the exact physics values it accepts, which immediately separates it from siblings like femm_open (existing files) or femm_problem_define (configures an already-created model). An agent can route to it without opening the schema.

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 lays out the downstream sequence explicitly: femm_problem_define next (units, planar/axi, depth, frequency), then geometry, materials, labels, boundaries, femm_solve. That is strong positional guidance. It never states the negative case (use femm_open / femm_session_open instead when a model or session already exists), so it stops short of a 5.

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