Audit the model against rules

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

Adds substantial behavior beyond the annotations: it writes immutable history on the server machine, offers compare modes (previous / a result path / none), maps unsupported evidence to not_assessed, caps the run at ten minutes, and defines skipped vs skippedCount. The 'Reads only' phrasing sits slightly awkwardly against readOnlyHint=false, but the saving behavior clarifies the model is only read while server-side output is written.

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?

Very dense and front-loaded: purpose first, then safety, then output/persistence behavior, then edge-case semantics. Some clauses are telegraphic fragments ('Unsupported evidence is not_assessed', 'skipped means incomplete'), which cost a little readability but keep it free of waste.

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?

An output schema exists, so return values need not be spelled out, and the description covers persistence, comparison, and status vocabulary. Still missing for a 7-parameter tool: what 'pack:model-health' actually contains, how a 'result path' for compare_with is supplied, and the relationship between timeout_seconds (default 120) and the ten-minute bound.

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 only 43%, so the description must compensate; it partially does by explaining the rules source (YAML/JSON file or the model-health pack), the save/compare choices, and step-count semantics. Several parameters (save, compare_with, rules_inline, timeout_seconds at 120s vs the stated ten-minute cap) are left to the schema or remain ambiguous, so it adds only moderate value.

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 concrete verb+resource: 'Audit one model with local YAML or JSON rules, or pack:model-health by default.' That is specific enough that an agent can tell it is a rule-driven audit rather than a snapshot or report. It does not explicitly distinguish itself from siblings such as revit_model_health or revit_audit_report, 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?

Gives useful operating defaults ('pack:model-health by default', 'Reads only', ten-minute bound), which implies when this is the right call. However it never says when to prefer revit_model_health, revit_audit_report, or revit_family_audit, and no prerequisites or exclusions are stated.

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