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

Although annotations are absent, the description discloses the destructive nature ('removes all color overrides') and the return value (count of processed elements). However, it does not discuss prerequisites, error behavior, or reversibility.

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, front-loading the purpose in the first sentence, and uses a clear structure with separate Args and Returns sections. Every sentence adds value without repetition.

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 simple one-parameter tool with no output schema, the description covers the parameter and return value sufficiently. However, it lacks preconditions (e.g., document must be open, category must exist) and does not specify the exact format of the return result, leaving some 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?

With 0% schema description coverage, the description adds essential meaning by explaining the parameter 'category_name' as the category to clear colors from and providing concrete examples ('Walls', 'Doors'). This significantly compensates for the schema's lack of description.

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 verb 'Clear' and resource 'color overrides for elements in a category', specifying the action and scope. It also distinguishes from sibling tools like 'color_splash' which applies overrides, making the 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?

The description provides examples of category names but gives no explicit guidance on when to use this tool versus alternatives. It does not mention when not to use it or recommend other tools for related tasks.

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?

No annotations are provided, so the description carries the full burden. It describes save behavior but does not mention potential data loss if save=False or whether the document is made inactive. More explicit warnings would improve transparency.

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 two short, front-loaded sentences. No unnecessary words, and the parameter description is clearly labeled under 'Args'.

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 single-parameter tool with no output schema, the description covers the core action and parameter. It could mention prerequisites (e.g., an active document must be open) but is otherwise sufficiently complete.

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 has 0% description coverage, so the description compensates by explaining the boolean parameter: 'If True, save the document before closing. If False (default), close without saving.' This adds meaningful semantics.

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 action: 'Close the active Revit document.' This verb-resource pair is specific and distinguishes it from siblings like open_document or save_document.

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 explains the save parameter but does not explicitly tell when to use close_document versus save_document or sync_with_central. Usage context is implied but not spelled out.

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?

With no annotations, the description must fully disclose behavior. It explains that elements with the same parameter value get the same color, and mentions gradient and custom colors. However, it does not disclose whether colors overwrite existing graphics, whether it applies to view-specific or element-level overrides, or if it requires an active Revit document.

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 two clear paragraphs and an Args/Returns list. It is front-loaded with the core action. However, the Args section is somewhat redundant with the schema, and the Returns statement is present but no output schema is defined.

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 4 parameters, no output schema, and no annotations, the description adequately covers the operation and parameter roles. However, it lacks details on prerequisites (e.g., active document, element selection), error handling, performance implications, and whether the coloring is persistent or view-specific.

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 0%, so the description must compensate. It explains each parameter with examples (e.g., 'Walls' for category_name, 'Mark' for parameter_name) and describes the effect of use_gradient and custom_colors. This adds significant meaning beyond the schema's bare types.

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's purpose: 'Color elements in a category based on parameter values' with a specific verb ('color') and resource ('elements in a category'). It distinguishes itself from the sibling 'clear_colors' tool, which reverses the 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 implies usage for color-coding based on parameters but does not explicitly state when to use it versus alternatives like 'clear_colors' or other modeling tools. No prerequisites or exclusions are provided, leaving the agent to infer 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?

Discloses key behaviors: no auto-transaction, print output returned, variables available, and UI operations outside transactions. No annotations provided, so description carries full burden.

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?

Well-structured with sections, front-loaded purpose, and helpful examples, though slightly lengthy.

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?

Covers tool purpose, variables, transaction handling, and usage tips sufficient for correct invocation, despite no output schema or annotations.

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 has 0% description coverage; description explains code parameter with context of available variables and print, and description parameter as label, adding significant meaning.

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 it executes IronPython code in Revit context, listing specific variables and capabilities, distinguishing it from siblings that handle specific operations.

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?

Implicit guidance is given through transaction and UI operation examples, but no explicit when-to-use or alternatives compared to siblings.

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?

No annotations exist, so description carries full burden. It explains truncated behavior and return fields, but does not explicitly state that the tool is read-only or describe side effects. For a read operation, this is adequate but not comprehensive.

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?

Description is concise (~8 lines), front-loaded with purpose, then return fields, special notes, and args. No fluff, well-organized.

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?

No output schema provided, but description details return fields and truncation handling. Covers enough for a list tool. Might need mention of document requirement, but overall complete given 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 0%, yet description explains all three parameters (limit, include_levels, include_location) with defaults and purpose. This compensates well for schema gaps. Could mention limits on range, but still strong.

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?

Purpose is clear: 'Get elements visible in the currently active view in Revit.' The verb 'get' and resource 'elements' are specific, with context 'visible in active view.' However, it does not explicitly differentiate from siblings like get_current_view_info or list_revit_views.

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?

No guidance on when to use this tool versus alternatives (e.g., execute_revit_code, list_revit_views). It mentions handling truncation but provides no exclusions or context about prerequisites like an open document.

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?

No annotations provided, so description must carry the burden. It describes return values but omits potential side effects (unlikely) or error conditions (e.g., if no view is active). The 'get' verb implies read-only, but this is not confirmed. Misses explicit safety guarantees.

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 concise sentences followed by a bullet list of seven items. Every line adds information without repetition or fluff. Front-loaded with the primary purpose.

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 no output schema, the description adequately explains return values with a detailed list. However, it does not cover prerequisites (e.g., an open document) or potential errors. For a simple read tool, this is mostly sufficient.

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?

No parameters exist, so baseline is 4. The description adds value by listing returned fields, which compensates for the absence of an output schema. No parameter details needed.

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?

Clearly states the action ('get') and the resource ('detailed information about the currently active view'), which distinguishes it from sibling tools like get_revit_view (needs a view ID) and list_revit_views (lists all views). The verb+noun structure is specific.

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?

Implicitly distinguishes usage by specifying 'currently active view', indicating no parameter required. Does not explicitly state when not to use, but the context (no parameters, sibling tools) makes it clear. Lacks explicit exclusions or alternative recommendations.

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 lacks behavioral details. Since no annotations are provided, the description should disclose traits like read-only nature, data freshness, or potential performance impact. It only states 'get info', which is insufficient for safe 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 a single sentence, front-loaded, and contains no extraneous words. However, 'comprehensive information' is broad and could be more precise, slightly reducing effectiveness.

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?

Despite low complexity (no params, no output schema), the description is too vague. It does not indicate what specific information is returned, leaving the agent with an ambiguous expectation. A description of the response structure would improve completeness.

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 tool has zero parameters, and the schema coverage is 100% (vacuously). Per the calibration guidelines, baseline for 0 params is 4. The description adds no parameter info because none are needed.

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 gets information about the current Revit model, using a specific verb and resource. However, 'comprehensive information' is vague and does not distinguish it from siblings like get_revit_status or get_current_view_info, which also provide model-related data.

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?

No guidance on when to use this tool versus alternatives. It does not specify prerequisites, context, or when not to use it. Siblings exist that might be more appropriate for specific queries, but no comparison is provided.

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?

With no annotations, the description adequately discloses it is a read-only status check. For a simple health probe, this is sufficient, though it could mention potential return values or error handling.

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?

A single, well-structured sentence that efficiently communicates the tool's purpose with no unnecessary words.

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 simplicity of the tool (no parameters, no output schema), the description fully captures its functionality. No additional details are needed.

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?

No parameters exist, and schema description coverage is 100%. According to guidelines, 0 parameters yields a baseline of 4, and the description adds no param info since none are needed.

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 checks if the Revit MCP API is active and responding, using a specific verb and resource. It distinguishes from sibling tools which perform specific actions like coloring or closing documents.

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 implies use as a connectivity check but does not explicitly state when to use it versus alternatives or provide exclusion criteria. It's clear from context but lacks explicit guidance on prerequisites or when not to use.

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?

No annotations provided, so description carries full burden. States 'export' but doesn't clarify if it's read-only (implied but not explicit), or disclose side effects, permissions, or output file details. Average transparency.

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?

Single sentence, no superfluous words. Concise but lacks structured details that would improve usability (e.g., expected output format).

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?

Tool has low complexity (1 param, no output schema, no annotations), but description omits crucial details: output format (file path, base64?), how to retrieve the image, and error conditions. Incomplete for practical 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 0%; description adds no meaning to the parameter 'view_name'. Does not indicate valid values (e.g., must match a view from 'list_revit_views') or format. Only the parameter name is conveyed.

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?

Description clearly states the verb 'export', resource 'Revit view', and outcome 'image'. It effectively distinguishes from siblings like 'list_revit_views' (listing vs. export) and 'get_current_view_info' (info vs. image).

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?

No guidelines on when to use this tool vs. alternatives. Missing context on prerequisites (e.g., open document) or when to prefer other tools like 'get_current_view_info' or 'open_document'.

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?

With no annotations, the description must fully disclose behavior. It notes auto-detection of installed versions, polling until ready, and native worksharing dialog. However, it does not clarify whether the tool is blocking or asynchronous, nor does it mention any return value or side effects beyond launching.

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 with a concise intro, a key behavioral note about workshared files, and a clear Args list. Every sentence adds value, and the most important information 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 lack of an output schema, the description does not specify what the tool returns (e.g., success status, process ID, or connection handle). It mentions polling until ready but not the outcome. This leaves a gap in understanding the tool's complete behavior.

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 0%, so the description carries the full burden. It thoroughly explains each parameter in the Args section: file_path (file types, optional), version (year, default latest), language (code, optional), and timeout (seconds, default 120). This adds significant meaning beyond 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 'Launch Revit on this machine' with a specific verb and resource. It distinguishes from sibling tools like open_document by explaining that for workshared files, Revit shows its native dialog, and suggests using open_document for more control.

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 for when to use the tool (to launch Revit) and gives an alternative for workshared files. However, it does not explicitly state when not to use this tool, though the alternative is well-explained.

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?

No annotations are provided, so the description carries the full burden. It mentions the return type (list of parameters with types and sample values) but does not disclose that the operation is read-only, the potential cost, or error handling. The description is insufficient for full behavioral transparency.

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 with an initial summary followed by Args and Returns sections. It is concise yet informative, with no wasted words. The first sentence immediately states the purpose.

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 simple schema (one required parameter, no output schema), the description covers the key aspects: what the tool returns and how to specify the category. However, it lacks details on error handling or behavior for invalid categories, which would improve completeness.

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 no description for the single parameter (0% coverage). The description adds meaning by naming it 'category_name' with an explicit example ('Walls', 'Doors'), which helps the agent understand valid inputs. This compensates for the schema's lack of description.

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's purpose: 'Get available parameters for elements in a category' and explains it helps discover parameters for coloring. It distinguishes from sibling tools like list_families by focusing on parameters, though sibling differentiation is not explicit.

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 implies when to use (when needing parameters for coloring) but provides no explicit when-not-to-use or alternatives. It does not guide the agent to avoid this tool for other purposes.

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?

No annotations provided, so description must convey behavioral traits. It indicates a read operation ('get') but doesn't disclose side effects, required document state, or pagination behavior. Lacks depth needed to fully inform safe 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?

Two sentences, no filler. First sentence states purpose, second gives actionable usage hint. Efficient and 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?

Covers basic functionality and filter option, but lacks output format details, prerequisites (e.g., open document), and explanation of 'limit' parameter. Adequate but leaves gaps for an agent.

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 description must compensate. It explains the 'contains' parameter well (filter by substring, case-insensitive) but does not explain 'limit' parameter (default 50, role unclear). Partial compensation.

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?

Clearly states it gets a flat list of family types in the Revit model, specifying the resource (family types) and action (get). Differentiates from siblings like list_family_categories by focusing on types rather than categories.

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?

Provides guidance on using the 'contains' parameter for filtering with case-insensitive substring match, but does not mention when to use this tool versus alternatives like list_family_categories or any prerequisites.

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?

With no annotations, the description bears full burden. It states 'Get a list' which implies a read-only operation, but does not disclose other behavioral traits such as whether it requires an open document, performance considerations, or error conditions. It is minimally adequate.

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 a single sentence with no wasted words. It is front-loaded and efficient.

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 simplicity (no params, no output schema), the description is minimal. However, it does not explain what a 'family category' is (domain knowledge assumed) or what the returned list contains (e.g., names, IDs). This leaves some ambiguity for an AI agent.

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 tool has zero parameters, so the baseline is 4 per rules. No parameter information is needed, and the description does not add any superfluous parameter detail.

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 'Get' and resource 'list of all family categories', clearly stating what the tool does. It effectively distinguishes from sibling tools like 'list_families' (which returns families, not categories) and 'list_category_parameters' (which returns parameters of categories).

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 no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or context. Given the sibling tools, an agent might infer usage, but explicit guidance is absent.

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?

No annotations provided. The description only indicates a read operation via 'Get', but fails to disclose any behavioral traits such as side effects, authentication needs, or rate limits, leaving the agent underinformed.

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?

Single clear sentence, no wasted words. Front-loaded with verb and resource, immediately conveying the tool's purpose.

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 simple list tool with no parameters and no output schema, the description is nearly complete, specifying the domain ('current Revit model'). Lacks mention of return format or read-only nature, but acceptable for low 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?

No parameters in the schema; schema coverage is 100% trivially. The description adds no parameter information, but baseline 4 is appropriate for zero-parameter tools as the schema already defines nothing.

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 includes a specific verb 'Get' and resource 'list of all levels in the current Revit model', clearly distinguishing it from sibling tools like list_families or list_revit_views.

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?

No guidance on when to use this tool versus alternatives. The description only states what it does, leaving the agent to infer applicability without any explicit context or when-not conditions.

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?

No annotations are provided, so the description carries full burden. It states the return is a list with executable paths, but does not specify error handling (e.g., what happens if no Revit is installed) or any side effects. For a simple query tool this is adequate but could be more explicit.

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 two sentences long with no wasted words. The first sentence states the purpose, the second adds return detail and usage hint. Concise and 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 no parameters and no output schema, the description fully covers what the tool does, what it returns, and why to use it. No additional information is needed for an agent to select and 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?

The tool has no parameters and schema coverage is 100% (trivially). The description does not need to add parameter meaning, and it correctly implies no input is required.

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 the specific verb 'Discover' and clearly identifies the resource as 'all Revit versions installed on this system'. It distinguishes the tool from siblings by stating it should be used to check availability before calling launch_revit, which is a sibling tool.

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 'Use this to check what's available before calling launch_revit', providing clear context for when to use this tool. It does not include negative guidance or alternatives, but the usage hint is direct and useful.

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?

No annotations provided, so description carries full burden. It states a read operation but does not disclose whether it returns names, IDs, or other metadata. The term 'exportable' is undefined. For a simple list tool, this is minimally transparent.

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 a single sentence with no wasted words. It is front-loaded with the key action and resource.

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 no output schema and no parameters, the description is adequate but lacks detail on what constitutes an 'exportable view' and what the list contains (e.g., names, IDs). More context would improve completeness.

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?

No parameters exist in the input schema, and schema description coverage is 100%. The description does not need to add parameter details, and it correctly implies no input is required.

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 ('Get') and clearly identifies the resource ('all exportable views') and context ('current Revit model'). It distinguishes itself from siblings like 'get_current_view_info' which deals with a single view.

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?

No explicit guidance on when to use this tool vs alternatives. While the tool's purpose is straightforward, it would benefit from mentioning that it lists views, not elements, and that other tools like 'get_current_view_elements' serve different purposes.

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?

Despite no annotations, the description explains detach behavior ('preserves worksets but severs the link') and audit functionality. However, it does not cover error handling (e.g., file not found), state changes (e.g., closing current document), or return value.

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 (10 lines), front-loaded with the main purpose, and structured with a brief summary followed by parameter explanations. Every sentence adds value.

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?

Covers main purpose, file types, and optional behaviors but lacks details on return output (if any), error scenarios, and implications for the current document state. Given no output schema or annotations, more completeness would be beneficial.

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?

With 0% schema description coverage, the description adds meaning beyond schema titles: file_path specifies allowed extensions, detach explains its effect on central linkage, audit clarifies corruption checking. This compensates for the schema's lack of description.

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 verb 'Open' and specific resource 'Revit document file', supported file extensions, and options for workshared files, effectively distinguishing it from siblings like close_document and save_document.

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?

No guidance on when to use this tool versus alternatives (e.g., sync_with_central for workshared files). Prerequisites like requiring a running Revit instance are implied but not explicit.

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?

No annotations provided, so description must carry burden. Only states 'Place a family instance' implying creation, but lacks details on side effects (e.g., document modification, error handling).

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 short but at cost of completeness. No structure like bullet points; fails to leverage space for parameter or usage 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 8 parameters, nested properties object, no output schema, and no annotations, the description is severely incomplete. Lacks coordinate system, units, required preconditions, and property format.

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%, and the description only mentions 'specified location', ignoring all 8 parameters including family_name, coordinates, rotation, level_name, and properties.

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?

Clearly states the action ('Place') and resource ('family instance') with location context, distinguishing from sibling tools like list_families or execute_revit_code.

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?

No guidance on when to use this tool versus alternatives (e.g., execute_revit_code). Does not mention prerequisites like family must be loaded or level must exist.

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?

No annotations are provided, so the description must fully disclose behavioral traits. It covers the main behaviors (save in place vs. Save As) but does not detail error conditions, overwrite behavior, or confirmation prompts. This is good but could be more comprehensive.

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 three sentences that efficiently convey purpose, usage, and parameter semantics. No superfluous words.

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 simple tool with one optional parameter and no output schema, the description is fairly complete. It explains the two modes of operation. However, it could mention potential errors (e.g., if file path is invalid or document not modified).

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?

With 0% schema description coverage, the description compensates by clarifying the file_path parameter: 'Optional path for Save As. If omitted, saves in place.' This adds meaning beyond the schema's bare type and default.

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 'Save the active Revit document,' specifying the verb (save) and resource (active Revit document). It distinguishes itself from sibling tools like open_document, close_document, and sync_with_central.

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 explains when to use the file_path parameter (for Save As) versus omitting it (save in place). It provides explicit context for both scenarios, though it does not mention exclusions or when not to use the tool.

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?

With no annotations provided, the description carries the full burden. It explains the function of each parameter (comment, compact, relinquish_all) and reiterates the tool's scope (workshared only). However, it lacks details on whether the sync is blocking, error conditions, or prerequisites (e.g., file must be saved). Still, above average disclosure.

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 main action, uses a clear header for the argument list, and is concise with no wasted words. Every sentence provides value.

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?

Considering the tool has 3 optional parameters and no output schema or annotations, the description covers the essential aspects: purpose, usage scope, and parameter semantics. It does not mention return value or potential errors, but for a synchronization tool these are often implicit. Completeness is high but not maximal.

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 has 0% description coverage, so the description fully compensates by explaining each parameter: comment is a sync comment visible in the log, compact compacts the central model, and relinquish_all relinquishes borrowed elements and worksets. This adds crucial meaning beyond the raw 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 'Synchronize the active workshared document with central,' which is a specific verb and resource. It also distinguishes itself from sibling 'save_document' by noting it only works with workshared documents.

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 provides when to use ('Only works with workshared documents') and when not to ('For non-workshared documents, use save_document instead'), including an alternative tool. This is exemplary guidance.

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