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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: supports single/multiple view activation, validates view element validity, filters template views, includes error handling, and specifies that the last successfully activated view becomes current. It also details error codes and response formats, though it doesn't cover permissions or rate limits.

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 sections (特性, 参数, 返回, etc.), but it's verbose and includes redundant information (e.g., JSON-RPC 2.0 specification mentioned twice, example output partially repeats return structure). Some sentences, like the note about 'mcp_tool使用时params不要有任何注释信息', don't add clear value for an AI agent.

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 complexity (2 parameters with 0% schema coverage, no output schema, no annotations), the description is highly complete. It covers purpose, parameters with semantics, return values with success/error structures, error codes, examples, and important behavioral notes (e.g., template view handling, multiple view activation behavior). No significant gaps remain for tool 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 0%, so the description must compensate. It thoroughly explains the parameters: 'ctx' as FastMCP context object, 'method' as JSON-RPC method name with default, and 'params' as a list of dictionaries with 'elementId' details. It provides examples and clarifies data types (Union[int, str]), adding significant value beyond the minimal 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 the tool's purpose: '激活并打开Revit中的视图' (activate and open views in Revit). It specifies the verb (activate/open) and resource (views in Revit), though it doesn't explicitly differentiate from sibling tools like 'get_view_data' or 'create_floor_plan_views'. The purpose is specific but lacks sibling comparison.

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 context through examples (activating single or multiple views) and notes (e.g., cannot activate template views). However, it doesn't explicitly state when to use this tool versus alternatives like 'get_view_data' or 'link_dwg_and_activate_view', nor does it provide clear prerequisites or exclusions beyond template view filtering.

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 effectively discloses key behavioral traits: supports batch calls, parameter passing, automatic parameter validation, and comprehensive error handling. It also specifies the JSON-RPC 2.0 protocol. However, it doesn't mention potential side effects, performance characteristics, or authentication requirements that might be relevant for a Revit API tool.

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 clear sections (description, features, parameters, returns, examples). It's appropriately sized for a tool with 2 parameters and complex functionality. The content is front-loaded with the core purpose. Some minor redundancy exists between the features list and parameter explanations.

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 complexity (generic function calling with JSON-RPC), no annotations, 0% schema coverage, and no output schema, the description provides substantial context. It covers purpose, features, parameters, return format, and includes multiple examples. The main gap is lack of output schema details, but the description specifies the return is 'JSON-RPC 2.0格式的响应' which provides some guidance.

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 (schema has no descriptions), the description fully compensates by providing detailed parameter semantics. It explains both parameters: 'method' as the JSON-RPC method name with default 'CallFunc', and 'params' as a list of dictionaries containing function names and optional parameters. The structure of the params dictionary is clearly documented with 'name' and 'params' fields.

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: '调用 Revit 函数服务，支持直接传递功能名称及其参数，遵循 JSON-RPC 2.0 规范' (Call Revit function service, supports directly passing function names and their parameters, follows JSON-RPC 2.0 specification). This specifies the verb (call), resource (Revit functions), and protocol (JSON-RPC 2.0). However, it doesn't explicitly differentiate from sibling tools like 'execute_commands' or 'get_commands' which might have overlapping functionality.

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 implied usage through the '特性' (Features) section and examples, showing it's for batch calling functions with parameters. However, it lacks explicit guidance on when to use this tool versus alternatives like 'execute_commands' or other specific creation tools. The examples help but don't establish clear boundaries.

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 full burden and does well by disclosing key behavioral traits: batch creation capability, automatic unit conversion (mm to feet), automatic type matching, width/height specification support, and comprehensive error handling. It also describes the JSON-RPC 2.0 protocol usage, though it doesn't mention permissions, side effects, or rate limits.

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 clear sections (特性, 参数, 返回, 示例) but contains some redundant information. The JSON-RPC 2.0 specification mention appears twice, and the 'mcp_tool使用时params不要有任何注释信息' note seems out of place. The content is valuable but could be more efficiently 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?

For a creation tool with no annotations and no output schema, the description provides excellent coverage: clear purpose, detailed parameters, comprehensive return format documentation, and a complete example. The main gap is the lack of usage guidelines compared to sibling tools, but otherwise it's quite complete for a 2-parameter tool.

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 and 2 parameters, the description fully compensates by providing detailed parameter documentation. It explains the 'method' parameter default value and purpose, and thoroughly documents the 'params' array structure including all 9 fields with their data types, units (millimeters), and semantic meaning (start/end coordinates, dimensions).

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 specific action ('创建电缆桥架' - create cable trays) and resource (in Revit), distinguishing it from siblings like create_ducts or create_pipes. The first sentence immediately establishes the tool's purpose with verb+resource specificity.

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 is provided about when to use this tool versus alternatives like create_ducts or create_pipes. The description mentions it's for cable trays but doesn't explain when cable trays are appropriate versus other routing systems, nor does it mention prerequisites or dependencies.

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 of behavioral disclosure. It mentions several behavioral traits: batch creation capability, automatic unit conversion (millimeters to feet), support for specifying family types/categories/host walls, and comprehensive error handling. However, it doesn't address important behavioral aspects like whether this is a read-only or destructive operation, what permissions are required, or any rate limits/performance considerations.

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 clear sections (特性/features, 参数/parameters, 返回/return, 示例/example), but it's quite lengthy. The JSON-RPC specification note and 'mcp_tool使用时params不要有任何注释信息' (when using mcp_tool, params should not have any comment information) seem unnecessary for tool selection. The example is comprehensive but could be more concise while still being helpful.

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 complexity (batch creation with multiple parameters), no annotations, and no output schema, the description does an excellent job of explaining what the tool does, its parameters, and return format. The detailed return structure documentation compensates for the missing output schema. The main gap is lack of usage guidelines compared to sibling tools, but otherwise this is quite complete for a creation tool.

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 description coverage is 0%, so the description must fully compensate. It provides extensive parameter documentation: explains the two main parameters (method and params), details all 8+ fields within the params array (categoryName, familyName, name, startX/Y/Z, hostId, offset), including data types, units (millimeters), and optional status. This goes far beyond what the minimal input schema provides and gives the agent complete understanding of parameter requirements.

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: '在Revit中创建门窗族实例，支持批量创建' (Create door/window family instances in Revit, supports batch creation). It specifies the exact action (创建/creation), resource (门窗族实例/door-window family instances), and distinguishes from siblings like create_walls, create_floors, etc. by focusing specifically on doors and windows.

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. It doesn't mention when to choose create_door_windows over create_family_instances (which appears to be a more general sibling tool) or other creation tools. There's no discussion of prerequisites, constraints, or appropriate contexts for this specific door/window creation functionality.

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 full burden and does well by disclosing key behavioral traits: batch creation capability, automatic unit conversion (mm to feet), automatic matching of duct and system types, and comprehensive error handling. It also describes the JSON-RPC 2.0 protocol usage. However, it doesn't mention permissions, rate limits, or side effects beyond creation.

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 sections (特性, 参数, 返回, 示例) but contains some redundant information. The JSON-RPC protocol mention appears twice, and the example is quite lengthy. While informative, it could be more streamlined by removing repetition and shortening the example.

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 creation tool with no annotations and no output schema, the description does well by covering purpose, parameters, return format (both success and error cases), and providing an example. It explains the JSON-RPC response structure which compensates for missing output schema. However, it lacks information about prerequisites, permissions, or integration context with other tools.

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 (schema only shows 'method' and 'params' as generic objects), the description fully compensates by providing detailed parameter documentation. It explains the 'params' array structure with 10 specific fields, their data types, units (millimeters), and purpose. This adds significant value beyond the minimal 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 '在Revit中创建风管' (create ducts in Revit) with the specific verb '创建' (create) and resource '风管' (ducts). It distinguishes from siblings like create_pipes, create_walls, etc. by specifying the exact resource type. However, it doesn't explicitly differentiate from other creation tools beyond naming the resource.

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 is provided on when to use this tool versus alternatives like create_pipes or other creation tools. The description mentions '支持批量创建' (supports batch creation) which hints at a use case, but doesn't provide explicit when/when-not scenarios or mention sibling tools as alternatives for different creation needs.

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 full burden and does well by disclosing multiple behavioral traits: batch creation capability, automatic unit conversion (millimeters to feet), multiple placement types, rotation/offset support, automatic family type/category matching, and comprehensive error handling. It also mentions JSON-RPC 2.0 compliance. However, it doesn't cover permission requirements or rate limits.

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 comprehensive but lengthy with multiple sections (features, parameters, returns, examples). While well-structured, it could be more front-loaded; the core purpose appears early, but detailed features and parameters follow. Some sentences like 'mcp_tool使用时params不要有任何注释信息' seem out of place and don't add value for AI tool selection.

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 complex creation tool with 2 parameters (but nested complexity), 0% schema coverage, no annotations, and no output schema, the description provides substantial context: detailed parameter semantics, return format specification, and comprehensive examples. It covers most needs but could benefit from more explicit guidance on when to use versus sibling creation tools.

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 (schema only shows 'method' and 'params' as generic objects), the description provides extensive parameter documentation: it explains the two main parameters (ctx and method), details 13 specific fields within the params array with descriptions, units, optionality, and examples. This fully compensates for the schema's lack of 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 clearly states the tool's purpose: '在Revit中创建族实例' (create family instances in Revit). It specifies the action (create) and resource (family instances), distinguishing it from sibling tools like create_walls or create_floors that create specific element types rather than generic family instances.

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 through the feature list (e.g., '支持批量创建多个族实例' - supports batch creation of multiple family instances) and parameter examples, but doesn't explicitly state when to use this tool versus alternatives like create_door_windows or create_walls. It provides context about placement types but lacks explicit guidance on tool selection.

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 of behavioral disclosure. It effectively describes key behaviors: supports batch creation, automatically skips existing views to avoid duplicates, and has error handling. These traits go beyond basic functionality and help the agent understand how the tool operates, though it could mention permissions or side effects.

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 but includes extensive technical details (JSON-RPC spec, example code, return structure) that may overwhelm. While informative, some sections like the full return format could be streamlined. It's structured but not optimally concise for quick agent comprehension.

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 complexity (batch creation tool with no annotations or output schema), the description is fairly complete. It covers purpose, parameters with semantics, behavioral traits, and return format, though it lacks output schema support. The example aids understanding, but more context on error scenarios or integration with siblings would enhance 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?

Schema description coverage is 0%, so the description must compensate. It details the 'params' parameter structure, specifying 'levelId' and 'viewName' with examples, which adds significant meaning beyond the generic schema. However, it doesn't explain the 'method' parameter's purpose or default value, leaving a minor gap in parameter understanding.

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: '根据给定标高创建楼层平面视图' (create floor plan views based on given elevations). It specifies the verb '创建' (create) and resource '楼层平面视图' (floor plan views), making the action explicit. However, it doesn't differentiate from sibling tools like 'create_walls' or 'create_floors' beyond the resource type, which prevents a perfect score.

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. It mentions JSON-RPC 2.0 compliance and technical usage notes (e.g., 'params不要有任何注释信息'), but offers no context about prerequisites, when this is appropriate compared to other creation tools, or any exclusions. This leaves the agent without practical usage direction.

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 full burden and does well by disclosing multiple behavioral traits: batch creation capability, automatic unit conversion (millimeters to feet), automatic floor type matching, support for structural/non-structural floors, automatic floor level determination from Z-values, and comprehensive error handling. This provides substantial context beyond basic functionality.

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 clear sections (特性, 参数, 返回, 示例), but contains some redundancy. The JSON-RPC specification mention appears twice, and the example output shows a different structure than described in the '返回' section (showing numeric IDs vs described object format). Some sentences could be more concise.

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 complex creation tool with no annotations and no output schema, the description provides substantial context. It covers functionality, parameters, return format, and includes a comprehensive example. The main gap is the lack of usage guidelines relative to sibling tools, but otherwise it's quite complete for understanding how to use the tool effectively.

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 (schema only shows generic 'method' and 'params' with no details), the description fully compensates by providing detailed parameter documentation. It explains the 'params' array structure, documents all nested fields (boundaryPoints with x/y/z coordinates, floorTypeName, structural flag), specifies units (millimeters), defaults (structural defaults to False), and optional parameters.

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: '在Revit中创建楼板，支持批量创建' (create floors in Revit, supports batch creation). It specifies the verb ('创建楼板' - create floors), resource (Revit), and distinguishes from siblings like create_walls or create_levels by focusing on floor creation specifically.

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. While it mentions batch creation and unit conversion, it doesn't explain when to choose create_floors over other creation tools like create_walls or create_rooms, nor does it mention prerequisites or constraints for floor creation in Revit.

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 full burden and does well by disclosing key behaviors: batch creation, unit conversion (mm to feet), automatic name conflict handling, and error handling. It also notes JSON-RPC 2.0 compliance and a usage note about params. However, it lacks details on permissions, side effects, or rate limits, leaving some gaps for a mutation tool.

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 purpose and features, but includes extensive parameter details, return format, and a lengthy example that may be verbose. While informative, it could be more streamlined by focusing on essential guidance rather than full JSON-RPC response structures. Some sentences (e.g., the example output) are lengthy but add 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?

Given no annotations, 0% schema coverage, and no output schema, the description does well by covering purpose, behaviors, parameters, and return format comprehensively. It includes an example for clarity. However, as a mutation tool in Revit, it could benefit from more context on when to use it or potential impacts, leaving minor 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 0%, so the description must compensate fully. It provides detailed parameter semantics: method defaults to 'CreateGrids', params is a list of dictionaries with specific fields (startX, startY, endX, endY, name, centerX, centerY), including units (mm) and optionality. This adds significant meaning beyond the minimal 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 the tool creates grids (axis networks) in Revit, specifying support for both straight and arc grids. It distinguishes from siblings like create_walls or create_floors by focusing on grid creation, though it doesn't explicitly contrast with them. The purpose is specific but lacks explicit sibling differentiation.

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 is provided on when to use this tool versus alternatives. While it mentions JSON-RPC 2.0 compliance and a note about params without comments, it doesn't explain prerequisites, context (e.g., when grids are needed in Revit workflows), or when to choose this over other creation tools like create_levels. Usage is 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes several behavioral traits: supports batch creation, automatic unit conversion (mm to feet), automatic handling of level name conflicts, and comprehensive error handling. However, it doesn't mention permissions needed, whether the operation is destructive/reversible, or rate limits. For a creation tool with no annotations, this provides 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 with clear sections (特性, 参数, 返回, 示例) and front-loads the core purpose. However, it includes some extraneous information like 'mcp_tool使用时params不要有任何注释信息' which seems like implementation detail rather than user guidance. Most sentences earn their place, but there's minor redundancy in the JSON-RPC format explanation.

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 this is a creation tool with no annotations, 0% schema description coverage, and no output schema, the description provides excellent completeness. It covers purpose, behavioral traits, detailed parameter semantics, return format (both success and error cases), and includes a practical example. The description fully compensates for the lack of structured metadata.

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 and only shows generic parameter names (method, params). The description compensates fully by providing detailed parameter semantics: method defaults to 'CreateLevels', params is a list of dictionaries where each contains elevation (in mm) and optional name (with default naming convention). This adds significant meaning beyond what the bare schema 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 clearly states the tool's purpose: '在Revit中创建标高，支持批量创建' (Create levels in Revit, supports batch creation). It specifies the exact action (create levels), the target resource (Revit), and distinguishes it from siblings like create_walls, create_floors, etc. The description goes beyond the tool name by mentioning batch creation capability.

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 context through the mention of JSON-RPC 2.0 specification and Revit, but doesn't explicitly state when to use this tool versus alternatives. No guidance is provided about prerequisites, when not to use it, or comparisons with other creation tools like create_floors or create_walls. The context is clear but lacks explicit usage directives.

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 of behavioral disclosure. It effectively describes key behaviors: batch creation capability, automatic unit conversion (millimeters to feet), automatic matching of pipe and system types, diameter specification, and error handling. It also documents the JSON-RPC response format for both success and failure cases. This provides substantial behavioral context beyond basic functionality.

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 clear sections (特性, 参数, 返回, 示例) but is quite lengthy with detailed parameter documentation and full response format specifications. While informative, some content could be more concise. The initial sentence about JSON-RPC 2.0 and MCP usage notes feels somewhat technical and could be streamlined for clarity.

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 complexity of a batch creation tool with 9 actual parameters, no annotations, and no output schema, the description provides exceptional completeness. It documents all parameters with units and examples, describes the JSON-RPC response format for both success and failure cases, includes a detailed usage example, and explains key behavioral features like unit conversion and type matching. This fully compensates for the lack of structured metadata.

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 (schema only shows 'method' and 'params' as generic objects), the description comprehensively documents all 9 actual parameters within the params array: pipeTypeName, systemTypeName, startX/Y/Z, endX/Y/Z, and diameter. It specifies units (millimeters), coordinate meanings, and provides concrete examples. This fully compensates for the schema's lack of detail and adds significant semantic 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 clearly states '在Revit中创建管道，支持批量创建' (create pipes in Revit, supports batch creation), which provides a specific verb ('创建' - create) and resource ('管道' - pipes). It distinguishes from siblings like create_walls or create_ducts by specifying pipes. However, it doesn't explicitly differentiate from create_cable_trays or create_ducts beyond naming the resource type.

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 like create_ducts or create_cable_trays. It mentions '支持批量创建' (supports batch creation) which could imply a usage scenario, but doesn't specify prerequisites, constraints, or comparative advantages over other creation tools. The only contextual note is about JSON-RPC 2.0 compliance, which is technical rather than usage 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?

With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it supports batch operations, automatically validates level element validity, uses transactional operations for data consistency, has comprehensive error handling, and notes specific behaviors like not creating rooms on levels without enclosed areas (without error). It also details the JSON-RPC 2.0 compliance and error codes.

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 clear sections (特性, 参数, 返回, 错误代码, 示例, 注意) and front-loaded purpose statement. While comprehensive, some sections like the detailed JSON-RPC response structure could be slightly condensed, but overall it's efficient with minimal 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?

Given the complexity of a creation tool with no annotations and no output schema, the description is remarkably complete. It covers purpose, parameters, return format (including both success and error responses), error codes, examples, and important behavioral notes. This provides sufficient context for an AI agent to understand and use the 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?

With 0% schema description coverage and 2 parameters, the description fully compensates by explaining both parameters in detail: 'method' is described as the JSON-RPC method name defaulting to 'CreateRooms', and 'params' is explained as a list of dictionaries containing 'elementId' for level identification. It provides format examples and clarifies that 'ctx' is a FastMCP context object.

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: '在指定标高上创建房间' (create rooms on specified levels/elevations). It specifies the verb ('创建' - create) and resource ('房间' - rooms), and distinguishes it from siblings like create_floors, create_walls, and create_room_tags by focusing on room creation specifically on levels.

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 implied usage context through the example and notes, showing it's for creating rooms on levels with enclosed areas. However, it doesn't explicitly state when to use this versus alternatives like create_family_instances or create_room_tags, nor does it mention prerequisites or exclusions beyond the note about levels without enclosed areas.

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 of behavioral disclosure. It does well by describing key behaviors: '自动跳过已有标签的房间' (automatically skips rooms with existing tags), '完善的错误处理机制' (comprehensive error handling), and specific error conditions for non-floor-plan views. It also explains the JSON-RPC 2.0 response format for both success and failure cases. However, it doesn't mention potential side effects, performance characteristics, or authentication requirements.

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 comprehensive but somewhat verbose and not optimally structured. While it contains valuable information, it mixes implementation details ('mcp_tool使用时params不要有任何注释信息' - don't include comments in params when using mcp_tool) with functional description. The information is front-loaded with the core purpose, but could be more efficiently organized with clearer section separation.

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 annotations, 0% schema coverage, no output schema, and 2 parameters, the description provides substantial context. It explains the tool's purpose, parameters, return format (including both success and error cases), behavioral characteristics, and includes practical examples. The main gap is lack of explicit differentiation from sibling tools, but overall it's quite complete for a tool with no structured metadata support.

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 and 2 parameters, the description provides excellent parameter semantics. It fully documents both parameters: 'method' (JSON-RPC method name, defaulting to 'CreateRoomTags') and 'params' (list of dictionaries containing 'elementId' for floor view element IDs). It includes detailed examples showing how to use both single and multiple view parameters, and explains the data types and structure thoroughly.

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 all rooms in the current view and create room tags for them). It specifies the verb ('创建' - create) and resource ('房间标签' - room tags). However, it doesn't explicitly differentiate from sibling tools like 'create_rooms' or 'create_family_instances', which prevents a perfect score.

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 some implied usage context through the '注意' (notes) section, stating it only works with floor plan views and skips rooms with existing tags. However, it doesn't explicitly guide when to use this tool versus alternatives like 'create_rooms' or 'create_family_instances', nor does it mention prerequisites or when-not-to-use scenarios beyond the floor plan requirement.

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 full burden. It mentions '完善的参数验证和错误处理' (comprehensive parameter validation and error handling) which is useful behavioral context. However, it doesn't disclose important traits like whether this is a destructive operation, permission requirements, rate limits, or what happens on partial failures in batch operations.

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 reasonably structured with sections for features, parameters, returns, and example. However, it includes redundant information ('遵循JSON-RPC 2.0规范' appears twice), and the example could be more concise. Some sentences don't earn their place in helping an AI agent understand tool usage.

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 batch creation tool with 3 parameters, 0% schema coverage, no annotations, and no output schema, the description does a fair job. It explains the core functionality and parameters well, but lacks important context about error behavior, side effects, and integration with the broader Revit context. The JSON-RPC framing adds some structure but doesn't fully compensate for missing behavioral details.

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 the description must compensate. It provides detailed parameter documentation in the '参数' section, explaining each parameter's purpose, required/optional status, and structure of the params array. This adds significant value beyond the bare schema. However, it doesn't explain the ctx parameter's role or provide examples of valid titleBlockType values.

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 '批量创建Revit图纸并添加指定视图' (batch create Revit sheets and add specified views), which is a specific verb+resource combination. It distinguishes from siblings like create_walls or create_floors by focusing on sheets/views rather than other Revit elements. However, it doesn't explicitly differentiate from all possible sheet-related tools (none exist in siblings).

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. It doesn't mention prerequisites, when this tool is appropriate versus other creation tools, or any exclusion criteria. The '特性' (features) section lists capabilities but not usage 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?

With no annotations provided, the description carries full burden and does well at disclosing behavioral traits. It describes automatic unit conversion (millimeters to feet), automatic wall type matching based on thickness, elevation handling with defaults, and comprehensive error handling. However, it doesn't mention whether this is a destructive operation (creates new elements) or any permission requirements, though 'create' implies mutation. The JSON-RPC format specification is also useful 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 with clear sections (特性, 参数, 返回, 示例) but is quite lengthy with multiple paragraphs and a detailed example. While all content is relevant, it could be more front-loaded with the core purpose. The technical note about 'mcp_tool使用时params不要有任何注释信息' seems out of place and doesn't add value for AI agent understanding. The example is helpful but extensive.

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 complexity of a batch creation tool with no annotations and no output schema, the description provides excellent completeness. It fully explains the tool's behavior, documents all parameters in detail, shows the complete return structure for both success and failure cases, and includes a practical example. For a mutation tool with rich functionality, this description gives the agent everything needed to understand 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?

With 0% schema description coverage (schema only shows 'method' and 'params' as generic objects), the description provides excellent parameter semantics compensation. It fully documents the params structure with detailed field explanations for startX, startY, endX, endY, height, width, and elevation including units (millimeters), optional status, and defaults. The description adds substantial value beyond the minimal schema, making parameters completely understandable.

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: '在Revit中创建墙体，支持批量创建' (Create walls in Revit, supports batch creation). It specifies the exact action (create walls), the target resource (walls in Revit), and distinguishes from siblings like create_floors or create_rooms by focusing specifically on walls. The description goes beyond just restating the name by adding context about batch creation and Revit environment.

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 context through the mention of Revit and batch creation, but doesn't explicitly state when to use this tool versus alternatives. While it distinguishes from siblings by focusing on walls, it doesn't provide guidance on when to choose create_walls over other wall-related tools (none listed in siblings) or when batch creation is preferable to individual operations. The JSON-RPC specification note is technical but doesn't guide usage decisions.

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 of behavioral disclosure. It does an excellent job describing key behavioral traits: it explicitly states this is a batch deletion tool, mentions transactionality for data consistency, describes detailed error handling and logging, and explains the JSON-RPC 2.0 response format. The only gap is not explicitly warning about the destructive nature, though '删除' (delete) implies this.

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 clear sections (特性, 参数, 返回, 示例), but it's quite lengthy with technical implementation details like 'mcp_tool使用时params不要有任何注释信息' and JSON-RPC specifications that may not all be essential for tool selection. Some information could be more concise while maintaining clarity.

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 destructive batch operation tool with no annotations and no output schema, the description provides substantial context: it explains the operation, parameters, return format, and includes a detailed example. The main gap is the lack of explicit warnings about the irreversible nature of deletion, though this is somewhat implied. Overall, it's quite complete given the 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?

With 0% schema description coverage and 2 parameters, the description provides comprehensive parameter information beyond what the schema offers. It explains the 'method' parameter's default value and purpose, details the 'params' structure including the required 'elementId' field with its data types, and provides a complete example showing proper usage. This fully compensates for the schema's lack of 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 clearly states the tool's purpose as '批量删除Revit元素' (batch delete Revit elements), which is a specific verb+resource combination. It distinguishes itself from sibling tools like 'find_elements', 'show_elements', 'move_elements', and 'update_elements' by focusing exclusively on deletion 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?

The description provides no guidance on when to use this tool versus alternatives. While it mentions supporting batch operations and JSON-RPC 2.0 compliance, it doesn't explain when deletion is appropriate versus other operations like updating or moving elements, nor does it mention any prerequisites or constraints for using this destructive operation.

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 full burden and does well by disclosing key behavioral traits: batch execution capability, add/remove functionality, automatic name matching, and error handling mechanisms. It also mentions JSON-RPC 2.0 compliance which informs the response format. The description doesn't contradict any annotations since none exist.

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 clear sections (特性, 参数, 返回, 示例) but contains some redundant information. The initial note about 'mcp_tool使用时params不要有任何注释信息' seems like implementation detail that doesn't help tool selection. The response format documentation is quite detailed but necessary given no output schema.

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 tool with no annotations, no output schema, and 0% schema description coverage, the description provides substantial context. It covers purpose, parameters with semantics, behavioral traits, and complete response format documentation. The main gap is lack of explicit differentiation from sibling tools like 'call_func'.

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 and 2 parameters, the description provides excellent parameter semantics. It explains the 'method' parameter default value and purpose, and thoroughly documents the 'params' array structure including nested 'name' and 'add' fields with their meanings. This fully compensates for the schema's lack of 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 clearly states the tool '执行指定的功能命令' (executes specified function commands) and mentions JSON-RPC 2.0 compliance. It distinguishes from siblings by focusing on command execution rather than element creation/deletion or data retrieval. However, it doesn't explicitly differentiate from 'call_func' which might be a similar 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 provides implied usage through examples showing how to add/remove function panels, and mentions '支持批量执行多个功能命令' (supports batch execution of multiple function commands). However, it lacks explicit guidance on when to use this tool versus alternatives like 'call_func' or other command-related tools, and doesn't mention prerequisites or constraints.

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 of behavioral disclosure. It does well by describing key behavioral traits: '支持批量多个查询条件' (supports batch multiple query conditions), '严格遵循JSON-RPC 2.0规范' (strictly follows JSON-RPC 2.0 specification), '详细的错误处理和日志记录' (detailed error handling and logging), and the complete error code mapping. It also specifies the return format structure for both success and failure cases. The main gap is it doesn't mention performance characteristics like rate limits or whether this is a read-only operation.

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 structured with clear sections (description, features, parameters, returns, error codes, example). However, it includes some redundant information: '遵循JSON-RPC 2.0规范' appears twice, and the technical note 'mcp_tool使用时params不要有任何注释信息' seems out of place in a user-facing description. The example is detailed but could be more concise. Overall, most content earns its place but could be more efficiently 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?

Given the complexity (2 parameters with 0% schema coverage, no output schema, no annotations), the description does an excellent job of providing context. It covers purpose, parameters with examples, return format, error handling, and includes a practical example. The main gap is the lack of explicit guidance on when to use this versus sibling tools. For a tool with this level of schema/annotation poverty, the description provides substantial compensatory value.

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 (schema only shows 'method' and 'params' with no semantic details), the description fully compensates by providing comprehensive parameter information. It explains that 'params' is a list of dictionaries containing 'categoryName' (with examples like 'OST_Views', 'OST_Walls', '门') and 'isInstance' (True for instances, False for types). It also provides context about BuiltInCategory vs Category.Name usage and view-related filtering guidance. The description adds significant value beyond the bare 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 the tool's purpose: '在Revit中按类别查找元素，返回匹配的元素信息列表' (find elements by category in Revit and return matching element information list). It specifies the verb '查找' (find) and resource '元素' (elements) with the constraint '按类别' (by category). However, it doesn't explicitly differentiate from sibling tools like 'get_selected_elements' or 'show_elements' that also retrieve element information.

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 some implied usage guidance: '和视图相关的请使用OST_Views类别作为categoryName参数' (for view-related elements, use OST_Views category as categoryName parameter). It also mentions '可指定查找实例或类型元素' (can specify to find instance or type elements). However, it doesn't explicitly state when to use this tool versus alternatives like 'get_selected_elements' or 'show_elements', nor does it provide clear exclusions or 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 provided, the description carries full burden and does well by disclosing key behavioral traits: it follows JSON-RPC 2.0 specification, has '完善的错误处理机制' (complete error handling mechanism), returns structured success/error responses, and operates without additional parameters. It doesn't mention rate limits, authentication needs, or performance characteristics, but covers core operational behavior adequately.

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 purpose but includes extensive sections (特性, 参数, 返回, 示例) that add value but create length. Some information like the JSON-RPC specification mention appears twice. The structure is logical but could be more streamlined, with the example being particularly detailed for a tool description.

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 tool with no annotations, 0% schema description coverage, and no output schema, the description provides substantial context: clear purpose, parameter semantics, detailed return structure with both success and error cases, and a comprehensive example. It doesn't explain the 'ctx' parameter or how errors manifest beyond the JSON structure, but covers most essential aspects given the 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 has 0% description coverage for its single parameter 'method', but the description fully compensates by explaining that 'method (str): JSON-RPC方法名，默认为"GetCommands"' (JSON-RPC method name, defaults to "GetCommands"). It also clarifies that 'mcp_tool使用时params不要有任何注释信息' (when using mcp_tool, params should not have any comment information), adding important usage context beyond the bare 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 the tool '获取所有功能商店里的功能' (gets all functions in the function store) and specifies it returns name, description, and tooltip information. It distinguishes itself from siblings by being a retrieval tool rather than a creation/deletion/update tool, though it doesn't explicitly differentiate from other 'get_' tools like 'get_locations' or 'get_selected_elements'.

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 context through '无需额外参数，直接获取所有功能' (no additional parameters needed, directly gets all functions), suggesting this is for comprehensive listing. However, it doesn't explicitly state when to use this versus alternatives like 'execute_commands' or 'call_func', nor does it mention prerequisites or exclusions beyond the JSON-RPC 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?

With no annotations provided, the description carries full burden and does an excellent job disclosing behavioral traits. It describes: batch query capability ('支持批量查询多个元素的位置'), automatic unit conversion ('自动处理单位转换（英尺转毫米）'), support for different element types ('支持点位置和曲线位置（直线和圆弧）'), error handling ('完善的错误处理机制'), and JSON-RPC 2.0 compliance. It also provides detailed error codes and response structures, giving the agent comprehensive behavioral understanding.

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 comprehensive but lengthy and not optimally structured. While it contains valuable information, it mixes implementation details ('mcp_tool使用时params不要有任何注释信息'), technical specifications, examples, and usage guidance without clear sectioning. The information is useful but could be more efficiently organized and front-loaded with the core purpose and key parameters.

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 complexity of the tool (JSON-RPC interface, batch processing, unit conversion, multiple element types) and the absence of both annotations and output schema, the description provides exceptional completeness. It covers purpose, parameters, return values, error handling, examples, and even practical applications. The agent has all necessary context to understand and correctly invoke this tool despite the lack of structured metadata.

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 and 2 parameters, the description fully compensates by providing detailed parameter semantics. It explains: 'ctx (Context): FastMCP上下文对象', 'method (str): JSON-RPC方法名，默认为"GetLocations"', and most importantly, details the complex 'params' parameter structure with 'elementId' field requirements and type preferences. The description adds substantial meaning beyond what the bare schema provides, including examples of parameter usage.

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: '获取Revit元素的位置信息，支持点和曲线元素' (Get location information for Revit elements, supporting point and curve elements). It specifies the resource (Revit elements) and action (get location information), and distinguishes from siblings like 'find_elements' or 'get_view_data' by focusing specifically on location data extraction.

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 some usage context at the end ('用途:找到定位后可用于创建门窗这种带有主体的族,族插入点就可以通过这个计算出来' - Purpose: After finding locations, it can be used to create families with hosts like doors/windows, family insertion points can be calculated from this). However, it doesn't explicitly state when to use this tool versus alternatives like 'find_elements' or 'get_selected_elements', nor does it provide clear exclusion criteria or prerequisites for usage.

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 full burden and does well. It discloses key behavioral traits: '无需额外参数，直接反映当前UI状态' (no additional parameters needed, directly reflects current UI state), '完善的错误处理机制' (comprehensive error handling), and details about the JSON-RPC 2.0 response format including success/error structures. It also mentions the tool follows JSON-RPC 2.0 specification. The description adds substantial value beyond what would be in basic 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 appropriately sized but not optimally structured. It front-loads the purpose but includes extensive technical details (JSON-RPC format, full response structures, example) that could be streamlined. The '特性' (features) section is useful, but the detailed return format explanation and lengthy example add bulk. Every sentence earns its place, but the organization could be more efficient for an AI agent.

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 (read operation with JSON-RPC protocol), no annotations, no output schema, and 0% schema coverage, the description provides good completeness. It covers purpose, behavior, parameters, return format, and includes an example. The main gap is lack of explicit sibling differentiation, but otherwise it gives the agent sufficient information to understand and invoke the 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?

The input schema has 0% description coverage with 1 parameter (method). The description compensates by explaining: '无需额外参数' (no additional parameters needed) and that 'method' defaults to 'GetSelectedElements'. It clarifies that parameters are minimal and primarily for JSON-RPC protocol compliance rather than functional input. For a tool with effectively 0 functional parameters, this provides good semantic context.

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: '获取当前Revit UI中选择的元素' (get currently selected elements in Revit UI). It specifies the exact resource (selected elements) and verb (get), and distinguishes from siblings like 'find_elements' (search) or 'show_elements' (display). The description is specific and unambiguous 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?

The description provides clear context for when to use this tool: '获取当前用户在Revit界面中选择的所有元素' (get all elements currently selected by the user in the Revit interface). It implies this is for real-time UI state reflection rather than searching or filtering. However, it doesn't explicitly state when NOT to use it or name specific alternatives among siblings, though the context makes the use case evident.

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 of behavioral disclosure. It effectively describes key traits: it's a read operation (提取/extracts data), organizes data by layers, includes error handling with specific codes, and follows JSON-RPC 2.0规范. However, it doesn't mention performance aspects like rate limits, data size limits, or whether it requires specific permissions. The error codes add valuable context beyond basic 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 well-structured with sections (特性, 参数, 返回, 错误代码, 示例), but it's overly verbose. The detailed return structure (with multiple example objects) and extensive example code could be condensed, as they repeat information. The core purpose is clear upfront, but later sections include redundant details that don't all earn their place.

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 annotations, 0% schema coverage, and no output schema, the description does a good job compensating. It fully explains parameters, return format (with success/failure structures), error codes, and provides usage examples. However, it lacks context about when this tool is appropriate versus siblings, and doesn't cover edge cases like empty views or large data sets.

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 the description must compensate. It documents all 2 parameters: 'method' (JSON-RPC method name, defaults to 'GetViewData') and 'params' (optional list of dicts, defaults to None). It explains their roles in the JSON-RPC context, which the schema alone doesn't provide. However, it doesn't detail what 'params' might contain or when to use it, leaving some ambiguity.

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: '读取当前视图中所有信息，包括文本和图形实体数据' (reads all information from the current view, including text and graphic entity data). It specifies the verb (读取/read), resource (当前视图/current view), and scope (所有信息/all information). This distinguishes it from siblings like 'get_selected_elements' (which gets only selected elements) or 'find_elements' (which searches with criteria).

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. It doesn't mention prerequisites (e.g., needing an active view), exclusions (e.g., not for editing), or comparisons to sibling tools like 'get_selected_elements' or 'find_elements'. The example shows basic usage but lacks contextual decision-making advice.

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 full burden for behavioral disclosure. It adds some useful context: mentions JSON-RPC 2.0 compliance, automatic parameter validation, and error handling mechanisms. However, it doesn't disclose important behavioral traits like whether this is a read-only or destructive operation, what permissions are required, or any rate limits. The description compensates somewhat but leaves significant gaps.

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 structured with sections (特性, 参数, 返回, 示例) but is overly verbose. It includes implementation details like JSON-RPC response structures and full example code that may not be necessary for an AI agent. The core purpose could be communicated more efficiently without sacrificing clarity.

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 annotations, 0% schema coverage, and no output schema, the description provides moderate completeness. It documents parameters and return values in detail, which is good. However, for a tool that appears to perform both linking and activation operations (potentially complex mutations), it should provide more context about side effects, prerequisites, and error conditions to be fully 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?

Schema description coverage is 0%, so the description must compensate. It provides detailed parameter documentation: explains that 'ctx' is a FastMCP context object, 'method' defaults to 'LinkDWGAndActivateView', and 'params' contains dictionaries with 'filePath' and 'viewName'. This adds substantial meaning beyond the bare schema. However, it doesn't fully document all parameter constraints or formats (e.g., what constitutes a valid filePath).

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: '链接本地 DWG 图纸并激活指定视图' (link local DWG drawings and activate specified views). It specifies both the action (link and activate) and the resource (DWG drawings and views). However, it doesn't explicitly differentiate from sibling tools like 'active_view' or 'create_floor_plan_views', which prevents a perfect score.

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. While it mentions JSON-RPC 2.0 compliance and lists features like automatic parameter validation and error handling, it doesn't specify scenarios where this tool is appropriate or when other tools (like 'active_view' for just activating views) should be used instead.

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 of behavioral disclosure. It does well by describing key behaviors: batch operation support, automatic unit conversion (millimeters to feet), return format details (ElementModelRequest), and error handling mechanisms. However, it doesn't mention potential side effects (e.g., whether movement affects element relationships or properties), performance considerations for large batches, or authentication requirements.

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 sections (特性, 参数, 返回, 示例), but it includes extraneous information. The note about 'mcp_tool使用时params不要有任何注释信息' is confusing and doesn't add value for tool selection. The JSON-RPC 2.0 compliance mention is repeated, and the example could be more concise. However, key information is front-loaded, and most sentences earn their place.

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 complexity (a mutation tool with batch operations, unit conversion, and structured returns), no annotations, and no output schema, the description does a good job. It explains parameters thoroughly, describes return formats for both success and failure cases, and provides an example. The main gap is lack of sibling tool differentiation and minimal usage context, but it's largely complete for understanding the tool's operation.

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 the description must fully compensate. It does this excellently by detailing both parameters: 'method' (JSON-RPC method name, defaulting to 'MoveElements') and 'params' (a list of dictionaries with specific fields: elementId, x, y, z). It explains units (millimeters for distances), structure, and provides a clear example. This adds substantial meaning beyond the bare 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 the tool's purpose with a specific verb ('移动' meaning 'move') and resource ('Revit元素' meaning 'Revit elements'), distinguishing it from siblings like 'delete_elements', 'update_elements', or 'parameter_elements'. It explicitly mentions batch operation support, which adds specificity beyond just moving elements.

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. While it mentions batch operations and unit conversion, it doesn't specify prerequisites (e.g., needing valid element IDs), exclusions (e.g., not for non-geometric elements), or when to choose other tools like 'update_elements' for different modifications. The only contextual note is about JSON-RPC 2.0 compliance, which is technical rather than usage-oriented.

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 of behavioral disclosure. It adds useful context: it mentions JSON-RPC 2.0 compliance, batch querying capabilities, error handling, and that it returns hash codes, names, and values. However, it doesn't cover important behavioral aspects like rate limits, authentication needs, whether it's read-only or destructive, or performance characteristics. The description provides some behavioral insight but leaves significant gaps.

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 sections (特性, 参数, 返回, 示例) but is overly verbose. It includes implementation details like 'mcp_tool使用时params不要有任何注释信息' (when using mcp_tool, params should not have any comment information) and JSON-RPC formatting specifics that aren't essential for tool selection. The example is detailed but could be more concise. Some sentences don't earn their place for an AI agent's decision-making.

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 2 parameters with 0% schema coverage and no output schema, the description does a good job compensating. It explains parameter semantics, provides a detailed return structure with success/error cases, and includes a comprehensive example. However, it lacks context on when to use this tool (guidelines) and some behavioral aspects (transparency), which slightly reduces completeness for a query tool with no 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?

The schema description coverage is 0%, so the description must fully compensate. It does this effectively: it explains that 'params' is a list of dictionaries containing 'elementId' and optional 'parameterName', and provides clear examples. It also clarifies that 'method' defaults to 'ParameterElements'. This adds substantial meaning beyond the bare schema, though it could briefly explain the 'ctx' parameter's role as a FastMCP context object.

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: '获取Revit元素的参数信息，支持批量查询和特定参数查询' (Get parameter information for Revit elements, supporting batch queries and specific parameter queries). It specifies the verb (获取/query), resource (Revit元素参数/Revit element parameters), and scope (批量/batch, 特定/specific). However, it doesn't explicitly differentiate from sibling tools like 'find_elements' or 'get_view_data', which prevents a perfect score.

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. While it mentions batch querying and specific parameter queries, it doesn't explain when to choose this over sibling tools like 'find_elements' (which might locate elements) or 'get_view_data' (which might get view-specific data). There's no mention of prerequisites, constraints, or typical use cases beyond the basic functionality.

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 full burden and does an excellent job. It discloses multiple behavioral traits: batch operation support, automatic handling of ID formats, automatic zooming to center, highlighting, adding to selection set, strict parameter validation, error handling, and JSON-RPC 2.0 compliance. This goes well beyond basic functionality 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 well-structured with clear sections (特性, 参数, 返回, 错误代码, 示例, 视图操作) and front-loads the core purpose. Some sections could be more concise (e.g., the JSON-RPC format details are quite verbose), but overall it's efficiently organized with each section earning its place.

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 tool with no annotations, no output schema, and 0% schema description coverage, the description provides exceptional completeness. It covers purpose, usage, parameters, return format, error codes, examples, and post-execution visual effects. The only minor gap is lack of explicit prerequisites, but given the context, this is complete enough.

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 and 2 parameters, the description fully compensates. It explains both parameters: 'method' (JSON-RPC method name, default 'ShowElements') and 'params' (list of dictionaries with elementId). It provides detailed structure requirements, data types, and examples. This adds substantial meaning beyond the bare 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 the tool's purpose: '在Revit视图中高亮显示指定元素' (highlight specified elements in Revit view). It specifies the verb (highlight/display) and resource (elements in Revit view), and distinguishes from siblings like 'find_elements' (search) or 'get_selected_elements' (retrieve).

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 this tool: for highlighting elements in Revit views, supporting batch operations. It doesn't explicitly state when NOT to use it or name alternatives, but the context is sufficiently clear given the sibling tools are mostly creation/update/retrieval tools rather than visualization tools.

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 of behavioral disclosure. It excels by detailing key behavioral traits: '支持事务处理' (supports transaction processing), '自动参数值类型转换' (automatic parameter value type conversion), '详细的错误报告和元素级状态跟踪' (detailed error reporting and element-level status tracking), '严格遵循JSON-RPC 2.0规范' (strictly follows JSON-RPC 2.0 specification), and '所有更新操作在Revit事务组中执行，任一更新失败自动跳过' (all update operations execute in Revit transaction group; any update failure is automatically skipped). This provides comprehensive insight into the tool's behavior beyond basic functionality.

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 sections like '特性' (features), '参数' (parameters), '返回' (return), '错误代码' (error codes), '示例' (examples), and '事务说明' (transaction explanation). However, it is verbose at approximately 500 words, with some redundancy (e.g., repeating JSON-RPC 2.0 specification). The front-loading is moderate—core purpose is stated early, but details could be more streamlined. Every sentence adds value, but efficiency could be improved.

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 complexity (batch updates with transactions, JSON-RPC), no annotations, 0% schema coverage, and no output schema, the description provides exceptional completeness. It covers purpose, features, parameters with semantics, return format (including success/failure structures), error codes, examples, and transaction behavior. This compensates fully for the lack of structured data, making the tool understandable and actionable 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?

Schema description coverage is 0%, so the description must compensate. It does so thoroughly by explaining all parameters: 'ctx (Context): FastMCP上下文对象' (FastMCP context object), 'method (str): JSON-RPC方法名，默认为"UpdateElements"' (JSON-RPC method name, defaults to "UpdateElements"), and details for 'params' including required fields (elementId, parameterName, parameterValue) with types and constraints. This adds significant meaning beyond the minimal input schema, fully documenting the 2 parameters (context signals indicate 2 parameters, though description lists 3—ctx, method, params—but ctx is likely implicit).

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: '批量更新Revit元素参数值' (batch update Revit element parameter values). It specifies the verb '更新' (update) and resource 'Revit元素参数值' (Revit element parameter values), distinguishing it from sibling tools like delete_elements, move_elements, or parameter_elements. The title is null, so the description fully defines the tool's function.

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 context through '批量更新' (batch update) and '遵循JSON-RPC 2.0规范' (follows JSON-RPC 2.0 specification), suggesting it's for batch operations within a JSON-RPC framework. However, it lacks explicit guidance on when to use this tool versus alternatives like parameter_elements or move_elements, or any prerequisites. The '事务说明' (transaction explanation) section provides some operational context but not comparative guidance.

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