ms_gui_new_structure_current

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, and it performs well. It reveals the non-obvious decision logic: never bypass authentication for ICSD/CSD/Materials Project/OQMD, ask the user instead; build the primitive/base document first; and do not name the initial document after a planned supercell size. These are genuine behavioral traits beyond what any schema could convey. It could add more detail on failure modes, but the disclosed traits are substantial.

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 content is dense and meaningful, but it is presented as one long run-on block separated by semicolons rather than scannable sentences. The core routing logic is front-loaded ('Unified entry point') which helps, but the wall-of-text format reduces readability for an agent parsing the definition. It is not overly long relative to the complexity of the tool, so it earns a middle score.

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 thoroughly covers the decision workflow and naming conventions, which is valuable context. However, for a tool with 26 parameters, no output schema, and no annotations, the complete absence of parameter semantics is a notable gap. An agent can understand the routing strategy but cannot reliably determine how to populate arguments like sourcePolicy, manualMode, minConfidence, or coordinateType to steer that routing. The workflow coverage is strong, but parameter coverage is a real hole.

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 only 35%, leaving roughly 17 of 26 parameters undocumented in the schema. The description does not compensate: it contains zero parameter-level guidance. It never explains how query, manualMode, atoms, sourcePolicy, minConfidence, or the cell parameters (a, b, c, alpha, beta, gamma) interact with the described decision workflow. For a high-parameter tool with low schema coverage, the description should have bridged this gap but does not.

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 identifies this as the 'Unified entry point for creating a new GUI structure' and states its exact scope: routing first-time structure creation. It explicitly distinguishes itself from siblings by saying 'Prefer this tool over direct create/import tools for first-time structure creation,' which separates it from ms_gui_create_current, ms_gui_import_current, and ms_gui_download_cif_import_current in the sibling list. The verb-resource pairing is specific and unambiguous.

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 explicitly states when to use it ('for first-time structure creation') and names the alternative category it supersedes ('direct create/import tools'). It also details the internal decision order (CIF-first, then auth-required sources, then manual fallback), which gives an agent a clear sense of the expected workflow. It stops short of enumerating the exact sibling tools it should NOT be used for (e.g., ms_create_molecule for pure molecules), so it is not fully exhaustive.

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