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

Beyond the readOnly/idempotent annotations, the description discloses return shape ('matchedElements and groups containing keys, count...'), unit conventions, null handling, empty-result behavior, error cases for invalid names, and failure modes ('missing document, read failure or timeout'). It also documents multi-instance behavior, which is valuable context not present in annotations.

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 longer than average but dense with useful information: usage, return shape, units, errors, and multi-instance caveats. It opens with a clear one-line summary and each subsequent sentence earns its place, though there is minor repetition with 'after revit_list_catalog' and 'Call revit_list_catalog first'.

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 14-parameter aggregation tool, the description covers the essential workflow, output contract, units, edge cases, and failure semantics. An output schema exists, so return-value details need not be fully restated. The only notable omission is detailed per-parameter examples, but the schema and description together are sufficient for correct invocation.

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 64%, so the description must add meaning beyond the schema. It does: it clarifies group_by semantics, numeric aggregation units, and the area_scheme interaction for area totals. However, some detailed parameter behavior is already supplied in the schema, so the description adds strong strategic context rather than filling every parameter gap.

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 first sentence 'Summarize matching elements by one or two fields after revit_list_catalog' identifies a specific verb, resource, and scope. It also clearly distinguishes the tool's aggregation purpose from revit_query_elements, which is for 'individual rows', so an agent can tell them apart.

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 says to 'Call revit_list_catalog first', states 'prefer this tool for counts and breakdowns', and warns to use 'revit_query_elements only for individual rows'. It also gives a concrete area-total strategy: 'group by level and select the area scheme'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral detail beyond that: absent collections are empty, non-workshared models have no worksets, errors are raised on missing documents/read failures/timeouts, and partial data is not returned. It also explains multi-instance behavior, which is important for correct invocation.

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 well structured and front-loaded: purpose, returned data, edge cases, follow-up tool, errors, and multi-instance behavior each have a compact sentence. There is no filler or redundant restatement of the tool name, and every sentence contributes useful 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?

Given the annotations, full parameter schema, and output schema, the description covers the remaining behavioral essentials: return content, empty collection semantics, error behavior, partial data prevention, and multi-instance routing. An agent has enough information to select and invoke this tool correctly without inference gaps.

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 100%, so the schema already documents all three parameters in detail INRThe description adds only general context about document selection and does not materially extend parameter semantics. With full schema coverage, the baseline of 3 is appropriate because the schema carries the parameter-documentation burden.

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 opens with a specific verb and resource: 'Read general information about the active Revit model.' It then enumerates exactly what will be returned: file name, Revit version, levels, area schemes, worksets, and view count. This clearly distinguishes it from siblings like revit_list_views, and explicitly routes to that tool for view analysis.

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 gives clear usage context, including the instruction to call revit_list_views next for view analysis and the multi-instance guidance about requiring the document parameter. The document parameter schema also points to revit_list_instances for listing all instances. It lacks an explicit 'do not use when...' exclusion, but the guidance is otherwise strong.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description goes well beyond this by disclosing error behavior, partial-data policy, unit conventions, rounding behavior, omitted geometry, and multi-instance routing. This is rich, accurate behavioral context with no contradiction.

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 appropriately sized for a tool with complex output behavior and is well-structured into distinct concerns: core purpose, returned data, units/geometry, errors, and instance routing. Every sentence provides useful information, and the core action is front-loaded.

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?

Given the presence of an output schema, the description does not need to restate return types, but it still covers essential operational details: units, rounding, omitted geometry, empty warnings, error behavior, and document disambiguation. An agent has everything needed to call this tool correctly.

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 100%, so the schema already documents all four parameters well. The description adds some reinforcement, such as document behavior and timeout errors, but does not materially extend parameter meaning beyond the structured schema. Baseline 3 is appropriate.

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 opens with a specific verb and resource: "Read parameters and geometry of an element by Revit ID." This clearly distinguishes the tool from listing, querying, or mutation siblings and states its exact scope. The title is generic, but the description fully compensates.

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 provides clear context, such as using roomCenterMm for placement inside rooms and requiring the document parameter when multiple Revit instances run. It does not explicitly name alternative tools or state when not to use this tool, so it falls short of the top score.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds substantial behavioral detail beyond them: it does not change the active view or write to the model, returns localPath without base64, raises errors for missing documents or existing destinations, uses specific timeout budgets, and explains multi-instance response behavior. No contradiction with annotations.

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 efficiently organized: purpose first, then return details, side-effect guarantees, error conditions, timeout behavior, and multi-instance guidance. Each sentence adds distinct information, and there is no redundant filler.

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?

Given the tool's moderate complexity, the 100% schema coverage, and the presence of an output schema, the description is complete. It covers what the tool returns, what it does not modify, failure modes, timeout behavior, and the multi-instance edge case—everything an agent needs to invoke it correctly.

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 100%, so the baseline is 3. The description reinforces parameter-relevant behavior such as exact view names, existing destination errors, and document disambiguation, but most of this is already present in the input schema. It adds little meaning beyond what the schema already provides.

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 a specific verb and resource: 'Export a selected view to PNG', and adds the purpose ('when numbers do not explain geometry'). It clearly distinguishes this from sibling query/list tools by framing it as the visual inspection tool for outlines, zones, and room boundaries.

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 gives clear context on when to use the tool ('when numbers do not explain geometry', 'use it to inspect outlines, zones and room boundaries') and when multi-instance disambiguation requires the document parameter. It does not explicitly name alternative sibling tools or exclusion conditions, but the intended usage is strongly implied.

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

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

The description adds substantial behavior beyond the readOnly/idempotent annotations: 100-entry cap per list, summary counts covering all entries, empty list behavior, per-entry failures reported as status Other, and timeout partials not returned. It also discloses multi-instance routing behavior, giving the agent a reliable mental model of edge cases.

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 efficiently structured: purpose first, then return shape, then limits, then error behavior, then multi-instance special case. Every sentence carries useful information; there is no redundancy or filler.

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 query tool with an existing output schema, the description covers the important non-obvious aspects: list cap, no pagination, empty-list behavior, failure statuses, timeout behavior, and multi-instance document requirements. Nothing an agent needs to call this correctly appears 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 description coverage is 100%, so the schema already fully documents all three parameters, including defaults and multi-instance behavior. The tool description mostly restates the document-required condition but adds no new parameter meaning beyond what the input schema provides, hence the baseline 3.

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 opens with a specific verb and resource: 'Read RVT, CAD and image link status'. It also gives the operational context ('before an export or hand-over') and names the exact data groups returned, making it easy to distinguish from sibling tools like revit_list_relations or revit_model_health.

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?

It clearly states when to use the tool ('before an export or hand-over') and gives multi-instance selection guidance: if more than one Revit instance is running, the document parameter is required. It does not enumerate alternatives or explicit exclusions, so it falls just 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.

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds meaningful behavioral details: empty catalogs return items=[], errors are raised for unknown sections, missing documents, read failures, or timeouts, and partial data is never returned. It also clarifies multi-instance behavior and localized naming for parameters. These are exactly the behavioral traits an agent needs to predict side effects and failure modes.

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 front-loaded with the core purpose, then progressively covers output shape, section values, tool selection, error behavior, and multi-instance context. Each sentence contributes distinct information, and there is no redundant filler. The structure makes it easy for an agent to scan and extract the key facts.

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 is comprehensive for a read-only catalog tool: it covers output, required section values, empty results, error conditions, partial data behavior, cross-tool routing, and the multi-instance document requirement. An output schema is present, so the description does not need to explain return shapes in detail. Nothing essential appears missing for correct invocation.

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?

The required section parameter has no description in the schema, but the tool description compensates by enumerating valid values: categories, family-types, levels, area-schemes, views, worksets, phases, or parameters. The document parameter's behavior is also reinforced by the description's guidance about multiple Revit instances. Since schema coverage is already fairly high at 75%, the description adds meaningful extra semantics rather than merely repeating the schema.

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 what the tool does: it returns catalog data with section and items containing names and section-specific IDs, categories, types, or counts. It also explicitly differentiates itself from siblings by saying to prefer revit_aggregate_elements for counts and revit_query_elements for individual rows. The required section values are enumerated, leaving little ambiguity about the tool's purpose.

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 provides explicit routing guidance: 'Start universal queries here, then prefer revit_aggregate_elements for counts and breakdowns; use revit_query_elements only for individual rows.' It also gives a concrete condition for when to use the document parameter, addressing multi-instance scenarios. This is strong, actionable usage guidance beyond what the schema provides.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat safety. It adds valuable behavioral context: fallback mechanisms in Local/SSH modes, HTTP mode limitations, and error behavior on transport failures. It also clarifies what fallback records look like (empty document, pluginResponding=false). This goes beyond the annotations.

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 concise, with key behavioral facts front-loaded (what it lists, then mode-specific behavior, then usage guidance). Sentences are efficient, though a bit dense. It avoids redundancy with the schema and annotations.

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?

Given an output schema exists, the description needn't explain return values in depth, but it does list main fields. It covers enough about behavior for an agent to decide when to call it and what to expect across modes. Minor missing: no explicit statement of idempotency, but that's covered by annotations. Overall, it is complete for this tool's complexity.

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?

The schema provides 100% coverage for the `document` parameter, including a detailed description. The description adds some context about using a unique substring, but that is also echoed in the schema. The description doesn't add significant meaning beyond the schema, so baseline 3 is appropriate.

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 the tool lists Revit processes and their active documents, naming specific returned fieldsrelation to siblings. It lists specific data returned (documentName, documentPath, etc.), which is precise, but it does not explicitly differentiate from sibling tools beyond its listing nature.

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 says 'Use this tool before choosing a unique document substring for other tools,' providing clear when-to-use guidance. It also explains the behavior of the `document` parameter partially in the description ('no matching instances return []'), but it doesn't explicitly state when NOT to use it in favor of a specific alternative. However, the contextual guidance is strong.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses empty-result behavior (elements=[]), strict error conditions for invalid relation/source/document/read failure/timeout, and promises no partial data. It also reveals the multi-instance routing behavior, adding meaningful context that annotations alone do not provide.

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 well-organized, front-loads the core purpose, and every sentence adds information: return format, required relation choices, source lookup guidance, error behavior, and multi-instance caveats. Despite covering many details, it remains compact and scannable.

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?

Given the tool's moderate complexity, an output schema, and rich parameter descriptions, the definition covers all necessary invocation details: valid relations, source requirements, timeouts, document routing, return shape, and failure semantics. Nothing an agent needs to call this 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?

The input schema leaves relation as a plain string, but the description defines the valid relation values and pairs each with the required source parameter (source_name or source_id). It also clarifies that source names come from revit_list_catalog and IDs from element queries, adding substantial meaning beyond the schema's property descriptions.

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 opens with a specific operation (read model object membership or dependencies) and enumerates the exact relation types (level-rooms, area-scheme-elements, view-template-dependents, group-elements, nested-family), which clearly separates it from sibling query tools. It also describes the returned data shape, leaving no doubt about what the tool does.

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?

It gives explicit direction on when to use name-based versus ID-based relations, instructs where to obtain source names (revit_list_catalog) and IDs (element queries), and explains the document parameter's role with multiple instances, even pointing to revit_list_instances as an alternative. This is actionable guidance that helps an agent select and invoke the tool correctly.

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

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

Beyond annotations, the description adds valuable context: empty results for no filter matches, total/processed counts, error behavior for missing document/read failure/timeout, no partial data, and multi-instance routing. This gives an agent a strong model of runtime behavior.

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 compact, front-loaded with the main purpose, and every sentence adds necessary information: return shape, empty behavior, workflow chaining, error behavior, and instance routing. No filler is present.

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?

Given the complete input schema, output schema, and annotations, the description covers all essential operational aspects: what is returned, what happens on empty/no matches, error and timeout behavior, and how to use the result with a sibling tool. Nothing critical 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 description coverage is 100%, so the schema already fully documents all five parameters. The free-text description does not add parameter-level meaning beyond what the schema provides, so the baseline of 3 applies.

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 opens with a specific verb and resource: finding non-template views before analyzing a view. It clearly scopes the tool to view discovery and distinguishes it from sibling tools like revit_view_elements or revit_list_warnings.

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?

It gives clear context for when to use the tool ('before analyzing a view') and how to chain results ('Use a returned name with revit_view_summary'). It also mentions multi-instance behavior, but does not explicitly state when-not-to-use alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds substantial behavioral context: empty results return groups=[], unmatched warning_text raises an error, failures/timeouts raise errors without partial data, and multi-instance behavior requires document. This goes well beyond what annotations alone provide.

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 organized into dense, purposeful paragraphs with the primary action front-loaded. Every sentence adds operational value, though the multi-instance note and error behavior are repeated in the schema parameter descriptions, adding slight redundancy.

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?

With an output schema present, the description need not explain return values in detail. It covers the core return shape, error conditions, no-partial-data guarantee, multi-instance document routing, and the recommended filter/inspection workflow. This is complete for an agent to invoke and iterate correctly.

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 100%, so the schema thoroughly documents all parameters. The description adds workflow guidance that ties parameters together ('Start without filters, then repeat with a returned warning_text and include_elements=true'), which is meaningful beyond the schema's isolated parameter definitions.

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 uses a specific verb and resource: 'Group model warnings by description text.' It clearly conveys the action and scope, but it does not explicitly differentiate itself from the sibling tool revit_view_warnings, so an agent might need extra inference to choose between them.

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 gives clear usage context: 'Start without filters, then repeat with a returned warning_text and include_elements=true to inspect one group' and explains the multi-instance document requirement. It does not explicitly state when to use this tool versus alternatives like revit_view_warnings, but the workflow guidance is strong.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses zero-count vs null semantics, the skipped list with errors, error conditions (missing document, read failure, timeout), and that timeout partials are not returned. This is strong behavioral disclosure with no contradiction.

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 front-loaded with the core purpose and return summary, then covers edge cases and alternatives in compact paragraphs. Every sentence adds value: return contents, null semantics, alternative tool, error behavior, and multi-instance routing.

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?

Given the output schema and 100% parameter schema coverage, the description supplies the missing behavioral context: return-value semantics, error conditions, routing rules, and sibling-tool routing. An agent has enough information to invoke the tool correctly and interpret results.

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 100%, so the baseline is 3. The description adds meaningful runtime semantics around the document parameter (multi-instance behavior) and timeout behavior (errors, no partials), which supplements the schema rather than repeating it.

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 opens with a specific verb and resource: 'Read model quality counts before an export or hand-over.' It clearly explains what is returned (project metadata, file size, counts, unit settings, top warning groups) and distinguishes itself from revit_list_warnings by directing users there for affected-element inspection.

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?

It states when to use the tool ('before an export or hand-over'), names the alternative for inspecting affected elements ('Use revit_list_warnings'), and gives multi-instance routing guidance ('If more than one Revit instance is running, document is required'). This is explicit, actionable context.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses important behaviors: no matching elements yield zero counts and empty samples, absent parameters count as missing, numeric zero counts as filled, invalid scope or timeout raises an error, partial data is never returned, and multi-instance routing requirements. This is rich behavioral context that annotations alone do not supply.

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 compact, well-organized, and front-loaded with the purpose. Every sentence earns its place: purpose, return data, edge cases, error behavior, and multi-instance routing. There is no fluff or repetition of schema content.

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 analysis tool with an output schema and strong annotations, the description is complete. It covers scope, return data types, edge cases, error behavior, timeout behavior, and multi-instance selection. An agent has enough context to select and invoke this tool correctly without needing to inspect the output schema.

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 70%, and the schema already documents the most important parameters (view, document, categories, parameters, sample_limit, timeouts). The description adds semantic edge-case meaning around parameters and filters: absent parameters are counted as missing, numeric zero is treated as filled, and sample limits apply only to samples while counts remain complete. A few parameters like level, workset, and include_types rely on their names and titles, but the overall parameter meaning is clear.

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 opens with a specific verb-resource pair: 'Count filled, empty and missing parameters before an export or hand-over.' This clearly identifies the tool's unique function and distinguishes it from sibling tools such as revit_query_elements, revit_view_summary, or revit_model_health.

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 gives an explicit use context: 'before an export or hand-over.' It also provides practical routing guidance for multi-instance scenarios ('document is required; otherwise any instance may respond'). It does not explicitly name alternative sibling tools or exclusion conditions, so it misses the full when-not-to-use guidance.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive (readOnlyHint=true, idempotentHint=true, destructiveHint=false). The description goes beyond annotations by disclosing that failures and timeouts raise errors, no partial result is returned, and multiple running instances may respond unless a document is specified. This is strong behavioral detail.

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 compact and front-loaded: purpose comes first, then return value, then error behavior, then the multi-instance caveat. Every sentence earns its place, and there is no redundant filler.

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 ping tool, the description covers all essential contexts: no active document, multiple instances, timeout/error behavior, and the expected response. The output schema exists, so return-value details are not required. Nothing critical is missing for correct invocation.

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 100%, with each parameter already documented in detail. The description's multi-instance note about 'document is required' reinforces the document parameter's schema description but does not add new parameter-level meaning. A baseline of 3 is appropriate.

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 a specific action: checking the RevitModelMcp connection without reading the model. It states the return value ('data="pong"') and distinguishes itself from sibling tools that read or aggregate model data. No ambiguity about the resource or operation.

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 gives clear context for when to use the tool: it works even when no document is active and explains the document requirement when multiple Revit instances are running. It does not explicitly name alternatives, but the health-check role is unambiguous and the multi-instance note adds actionable guidance.

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

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

The description adds substantial behavior beyond the readOnly/idempotent/non-destructive annotations: pagination semantics, unit conventions, geometry rounding and omission, the roomCenterMm caveat, error behavior with no partial data, and the document-selection rule. This is exactly the kind of context an agent needs.

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 dense but every sentence earns its place: purpose, return shape, units, geometry caveat, pagination, routing, errors, and instance selection. It is front-loaded with the primary action and then layers necessary operational detail.

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?

Given the tool's 18 parameters and the presence of an output schema, the description covers the high-risk operational details: paging, units, geometry caveats, failure modes, and multi-instance routing. Nothing essential for correct invocation 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 only 56%, and while the description does not enumerate every undocumented parameter, it adds global meaning that clarifies several: units for values, pagination for offset/hasMore, document for multi-instance selection, and geometry behavior for include_geometry. It does not fully compensate for all missing per-parameter descriptions, so it falls just short of a 5.

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 opens with a specific verb and resource: 'Read a page of matching element rows after revit_list_catalog.' It clearly communicates a paginated read operation and distinguishes it from sibling tools by naming the prerequisite catalog and the preferred aggregate alternative.

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?

It explicitly says to 'Call revit_list_catalog first' and to 'prefer revit_aggregate_elements for counts and breakdowns,' which gives the agent concrete routing guidance. It also provides the multi-instance condition for when document is required.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds substantial behavioral context beyond that: return units (mm, degrees) and precision (one decimal), list caps at 100 without pagination, empty sharedSiteFromLinks behavior, error-on-failure semantics with no partial data, and the multi-instance targeting rule. This is exactly the kind of non-obvious runtime behavior an agent needs.

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?

Five sentences, each earning its place: purpose, return format, list limits, error behavior, and instance targeting. The most decision-relevant information (purpose) is front-loaded, and dense clauses like 'capped at 100 without pagination, with total counts' convey maximum information per word without bloat.

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?

Given the tool's moderate complexity — three optional parameters, a read-only safety profile fully covered by annotations, and an output schema present — the description covers everything an agent needs to invoke it correctly: what it returns with units and precision, failure mode (error, not partial data), non-paginated caps, and the multi-instance routing rule. Timeout semantics are already fully specified in the schema, so nothing material 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 description coverage is 100%, so the baseline is 3. The schema's parameter descriptions are exceptionally detailed (document substring matching, timeout budget semantics, pickup timeout lifecycle), and the description body adds no parameter meaning beyond restating the multi-instance rule already present in the document parameter's schema description. The description neither compensates for gaps nor adds new param-level 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?

The description opens with 'Read project and survey coordinates before an export or hand-over' — a specific verb, resource, and temporal context that immediately tells an agent what the tool does and when it matters. It further enumerates the concrete outputs (base/survey points, active site, project locations, link offsets), making it clearly distinguishable from siblings like revit_document_info and revit_links_status without opening their schemas.

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 phrase 'before an export or hand-over' gives clear situational context for when to invoke this tool, and the document parameter's schema explicitly names revit_list_instances as the alternative when the agent needs all matching instances rather than a targeted document. However, the description does not explicitly state when NOT to use this tool relative to its closest siblings (e.g., revit_links_status for link health), so exclusions are incomplete.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses return structure (elements, total, offset, limit, hasMore; row fields), pagination behavior (empty elements[] on no matches/offset beyond; advance offset while hasMore=true), and error semantics (raises error; partial data not returned). It also covers multi-instance fallback, adding substantial behavioral context.

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 well-structured, front-loading the purpose, then enumerating output format, pagination, alternatives, and error behavior. Each sentence contributes meaning, though it is relatively long. The organization makes it scannable.

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?

Given the tool has an output schema (not shown but flagged true) and 7 parameters, the description covers return format, pagination, error handling, and multi-instance behavior. It provides enough context for an agent to call the tool correctly, and the output schema handles return detail. No critical missing context.

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 57%, so the description must compensate for undocumented parameters. It explains offset pagination ('advance offset while hasMore=true') and document usage ('any instance may respond'), but does not describe the categories filter or limit semantics explicitly. Some value is added, but gaps remain for parameters like categories that have only a bare array schema.

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 'Read one page of elements in a selected view' – a specific verb and resource. It also distinguishes itself from siblings by noting 'Prefer revit_view_summary for counts and category discovery; use this tool for individual rows and revit_element_details for all parameters,' making it unambiguous what tool to pick.

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?

Explicit usage guidance is provided: it directs agents to revit_view_summary for counts/category discovery, and revit_element_details for all parameters. It also explains when the document parameter is required ('If more than one Revit instance is running, document is required'), offering concrete operational context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral detail beyond that: the return shape ('header metadata and categories containing count and differentTypes'), empty-view behavior ('categories=[]'), error conditions ('missing document, unknown or unsupported view, read failure or timeout raises an error'), and the promise that 'partial data is not returned.' This is rich and non-contradictory context.

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 compact yet packs several key facts into a short paragraph: primary purpose, return shape, empty-view behavior, usage priority, error behavior, and multi-instance routing. It is front-loaded with the action and adds detail in logical order without redundancy or filler.

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?

Given that an output schema exists, the description need not explain return values in depth, yet it still covers the essential elements: what the tool does, when to use it, empty-view behavior, failure modes, and instance routing. For a read-only, idempotent tool with full schema coverage, nothing critical 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 description coverage is 100%, so the schema already fully documents all four parameters. The description's only parameter-related addition is the multi-instance note about document, which largely restates the schema's own document description. No new semantic value is added beyond the structured parameter definitions, so baseline 3 is appropriate.

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 begins with a clear verb+resource statement: 'Read element categories and counts for a selected view.' It further distinguishes itself from the sibling revit_view_elements by noting that it should be preferred for view counts and that revit_view_elements is for individual rows, making the tool's purpose 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?

Usage guidance is explicit: 'Prefer this tool for view counts; select relevant categories before calling revit_view_elements for individual rows.' It also provides a conditional rule for multi-instance scenarios ('If more than one Revit instance is running, document is required'), giving clear when-to-use and when-not-to-use context relative to alternatives.

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

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

Given the annotations already declare readOnlyHint=true and idempotentHint=true, the description adds value by explaining edge cases: 'no related warnings return warnings=[]', 'A warning may also involve elements outside the view', and the behavior of missing document or errors. It also mentions instance-specific behavior with multiple Revit instances, which is beyond the annotations.

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 well-structured and front-loaded with the core purposeaisublock. It is concise but covers important constraints and alternatives. It could be slightly more compact, but every sentence contributes necessary context.

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?

Given the presence of an output schema need not be explained, the description covers the semantics of the output (e.g., empty warnings list), error conditions, and multi-instance behavior. It is complete for an agent to know when to call it. Minor gaps like pagination or specific error messages are not critical.

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 100%, so the schema already documents all parameters. The description goes further by noting that the view name must be exact and case-sensitive, and that an exact name takes precedence over numeric ID interpretation. This adds meaning beyond the schema, which is valuable.

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 the tool reads warnings for elements in a selected view, differentiating it from model-wide warning tools. It specifies the resource (view) and action (read warnings), and the output structure is hinted at. This is specific and distinct from siblings like revit_list_warnings and revit_view_summary.

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 mentions when to use alternatives: 'Use revit_view_summary to inspect view contents, or revit_list_warnings for model-wide warning groups.' This provides clear guidance, though it could be more explicit about when NOT to use this tool, but the context is sufficient.

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