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

Annotations already declare readOnly=true and openWorld=false, so the safety profile is covered; the description adds genuinely non-obvious context — that no model and no account are needed, and that the grade lists and steel catalogues are CIVIL NX's own, published nowhere, with the answer explaining how to confirm one safely. That caveat about unreliable data is exactly the kind of disclosure annotations cannot carry. Output shape/verbosity is not described, so not a 5.

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 purpose is front-loaded, but the body is two enormous run-on sentences with heavy parenthetical enumeration (46 standards, 67 load types, 15 moving-load codes, 148 options). The catalogue detail is useful for routing yet unbroken and hard to scan, and the enumerated topic list — the most actionable part — sits near the end rather than up front.

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 read-only, no-parameter-required reference tool with no output schema, the description covers what an agent must know: the domains available, how to narrow with topic and search, that no model or account is required, and that certain data is unpublished and needs confirmation. Nothing needed to invoke it correctly is missing.

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 coverage is 67%, and the description still earns credit: it encodes a cross-parameter dependency the schema does not ('sections (shape: one shape)' — shape only applies to the sections topic) and clarifies that search alone searches every list while with topic materials it narrows to standards/grades. Parameter meanings are therefore richer than the schema alone, though the topic enum is essentially restated.

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 states precisely what the tool is: a structured reference of materials, sections, thicknesses, element rows, supports, loads and options, scoped to writing a CIVIL NX model via civil_write_tables. The resource is concrete and the 'needs no model and no account' clause pins it as a knowledge lookup rather than a model operation. It does not differentiate itself from the sibling midas_docs_search / midas_docs_read, which is the only thing keeping it from 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?

Usage is implied rather than stated: 'Structured reference for writing a CIVIL NX model through the API (civil_write_tables)' implies consult-before-writing, and 'search alone looks through every list and vehicle' explains the search-only mode. But there is no explicit when-to-use versus the obvious documentation siblings midas_docs_search and midas_docs_read, and no exclusion or prerequisite guidance beyond 'needs no model'.

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