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

No annotations are provided, so the description carries the disclosure burden. It informs the user that the operation affects only the active view and reverses color_splash, which is key behavioral context. It doesn't address edge cases like missing categories, but this is acceptable for a simple 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 concise and front-loaded: a single-sentence purpose, two short behavioral notes, and a compact Args block. Every sentence provides meaningful information with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter tool with no output schema, the description fully covers purpose, scope, and parameter semantics. It also references the related sibling tool, making it complete for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides no description, and schema coverage is 0%. The description compensates with an Args section that explains the parameter ('Category to clear') and gives an example ("Walls"), which fully covers the single parameter's meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Remove') and resource ('colour overrides from a category'), making the tool's function immediately clear. It also distinguishes itself from the sibling tool color_splash by explicitly noting it reverses that operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly indicates when to use the tool by stating it reverses color_splash and scopes to the active view. It doesn't explicitly exclude other circumstances or name alternatives, but the context is sufficient for a tool of this simplicity.

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

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

With no annotations, the description carries the burden of disclosing behavior. It explains the save parameter's effect, but it does not warn about data loss when save=False or describe behavior when no document is active. This is a notable omission for a destructive 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 extremely concise, consisting of a single purpose line and a compact Args block. Every sentence adds value with no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool, the description covers the core functionality and parameter semantics. However, it lacks important safety context (e.g., unsaved changes are lost when save=False) and does not address edge cases like no active document. Given no annotations, these gaps make it incomplete.

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 description clearly explains the 'save' parameter ('If True, save before closing; If False, close without saving'), adding meaning beyond the schema's type and default. However, it does not elaborate on what 'save' means in the Revit context (e.g., local save vs. central file).

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 'Close the active Revit document' with a specific verb and resource. It is distinct from sibling tools like open_document and save_document.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool (closing the active document), but it does not explicitly mention alternatives or exclusions. Its primary purpose is self-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, and it excels. It discloses key behavioral traits: overrides are applied 'in the ACTIVE view only,' 'other views are untouched,' 'overrides persist in the view until clear_colors is called,' and the return value includes 'the colour assigned to each distinct value, plus counts.' It also explains the gradient behavior and text-value limitations.

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: an introductory purpose sentence, a use-case sentence, behavior and return-value sentences, a prerequisite instruction, and a clear Args list. Every sentence adds useful information, and the front-loaded intro immediately communicates the tool's function.

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 4 parameters, no annotations, and no output schema, the description is remarkably complete. It explains scope (active view), longevity (until clear_colors), return values (color and counts), parameter examples, and gradient/custom-color behavior. The only minor omission is error handling for invalid categories, but this is not essential given the explicit prerequisite.

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 explain each parameter, and it does. Each arg includes an example and additional guidance (e.g., use_gradient 'Suits numeric parameters; poor for text values' and custom_colors as 'Optional hex colours to use in order'). This goes well beyond the schema's minimal names and types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Colour-code elements of a category by the value of one parameter.' It clearly states what the tool does and includes examples like 'phasing, fire rating, room department, wall type distribution' that distinguish it from sibling tools such as list_category_parameters or clear_colors.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear usage context: it is 'the fastest way to visually audit a model,' applies only to the active view, and explicitly instructs to 'Use list_category_parameters first to get a valid parameter_name.' It also mentions that overrides persist until clear_colors is called, which points to the relevant alternative for undo. It does not explicitly state when not to use this tool versus other coloring or modification tools, so it falls short of a 5.

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

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

With no annotations, the description fully discloses critical behavior: all lengths are in decimal feet and unaffected by project display units, with conversion guidance (divide by 304.8 for mm). It also explains default behavior for omitted parameters, the return value (id, name, category), and that errors list available names rather than making the agent guess blindly.

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 long but well-structured and every sentence adds value. It front-loads the core purpose, then critical unit warning, return value, usage references, exclusions, and an organized Args list. No redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 13 parameters and no output schema, the description covers all necessary context: defaults, unit system, error behavior, exclusions, and references to sibling tools for valid values. It states the return shape (id, name, category) and leaves little ambiguity for invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The Args section adds rich meaning beyond the raw schema: explains element_kind options, unit expectations for coordinates, per-parameter defaults (e.g., lowest level, first found type), and which parameters apply only to walls vs pipes. 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 opens with a specific verb and resource: 'Create a wall, structural beam, or pipe running between two points.' It clearly distinguishes from siblings like create_surface_based_element and place_family, and further clarifies scope by excluding ducts, cable trays, and curved walls.

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?

Explicitly states when to use this tool and alternatives: 'Use list_levels to see valid level_name values, and list_families for beam types.' It also says 'Does NOT create ducts, cable trays, curved walls... Use execute_revit_code for those,' providing clear when-not-to-use guidance.

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

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

With no annotations, the description carries full behavioral burden. It discloses the decimal-feet requirement, automatic closing of the boundary, planarity/non-self-intersection constraints, return value (id, name, category), version requirement for ceilings, and the 'floors only' restriction for structural. This is thorough and non-misleading.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized and front-loaded: purpose statement, critical coordinate note, boundary rules, return value, limitations, version note, and a structured Args block. Every sentence adds meaningful information without 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?

For a creation tool with no output schema and no annotations, the description covers all essential aspects: parameter semantics, defaults, constraints, return information, and version-specific behavior. It is complete enough for an agent to use the tool without additional context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 0% schema description coverage, the description's Args block explains all 5 parameters: element_kind values, boundary structure with an example, level_name default, type_name default, and structural scope. This fully compensates for 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 opens with 'Create a floor or ceiling from a closed boundary outline,' which uses a specific verb and resource. It distinguishes itself from sibling tools by referencing create_line_based_element for coordinate format and clearly scoping the element type to floors/ceilings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage guidance is explicit: it states unsupported cases (openings, sloped floors, arcs) and directs users to execute_revit_code for those scenarios. It also documents the required coordinate system and the host-level default, making when-to-use and when-not-to-use very clear.

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

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

With no annotations, the description fully carries behavioral disclosure. It details destructive nature, cascading deletions (deleted_count can exceed ids), dry run limitations (cannot predict cascades), and specific failure cases (pinned, owned by another user, structurally required).

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 front-loads the core purpose in the first sentence, then layers usage guidance, behavioral caveats, and parameter clarification. Every sentence adds value, and the structure guides the agent from safe usage to edge cases.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is exceptionally complete for a destructive tool. It covers purpose, when to use, alternatives, dry run behavior, cascades, limitations, and parameter semantics, leaving no critical gap—even without an output schema or annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has no descriptions (0% coverage), so the description compensates fully. It explains element_ids must be explicit and non-empty, and dry_run returns what would be deleted without changing anything. The dry_run parameter is clearly tied to the usage guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Delete elements from the model, by element id.' It also clearly distinguishes from siblings by stating it does NOT accept a category or filter, directing to reset_model for category-wide clearing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is provided: 'Prefer calling once with dry_run=True first' and 'use reset_model for category-wide clearing.' It also clarifies when not to use it (no category/filter) and when dry run is especially advisable (when ids came from a filter).

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

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

No annotations are present, so the description carries full burden. It discloses return fields, that category_counts is always computed, truncation flag, and instructions to compare total_elements vs returned_elements and increase limit, providing strong behavioral insight beyond the tool's name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded with the main purpose, followed by return details, truncation handling, and parameter explanations. Every sentence contributes information, with no redundant filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no output schema, the description sufficiently covers return values, truncation handling, and optional parameter effects. It covers the tool's core behavior and edge cases (truncation) completely for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema only provides titles and defaults, so the description fully compensates by explaining limit as maximum number to return and include_levels/include_location semantics with exact output implications. This adds meaning the schema lacks.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the precise verb 'Get' and specifies the resource 'elements visible in the currently active view in Revit', clearly distinguishing it from sibling tools like get_selected_elements or list_revit_views. The scope is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly states it retrieves elements in the active view, implying when to use it, but it does not explicitly contrast with alternative tools such as get_selected_elements or get_revit_view, nor does it provide exclusion criteria. This is acceptable context but lacks explicit alternative naming.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It openly lists the specific return fields (view name, type, ID, scale, detail level, crop box status, etc.), which tells the agent what to expect from the tool. It does not mention read-only status explicitly, but 'Get' implies a read operation with no side effects. This is better than many tools that fail to describe outputs.

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 extremely concise: one sentence stating the purpose, followed by a bullet list of the comprehensive information returned. Every sentence earns its place, and the structure is front-loaded with the primary purpose. No filler or 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?

For a zero-parameter, read-only tool with no output schema, the description is quite complete—it lists all the key data fields the tool returns. It lacks explicit guidance about when to use this versus get_revit_view, but the purpose is clear enough that this is a minor gap. Overall, it adequately covers the relevant context for an agent to select 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 tool has zero parameters, and the schema is an empty object. Per the rubric, a baseline of 4 is appropriate for 0 parameters since there is nothing for the description to add. The description does not need to explain parameters that do not exist.

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 detailed information about the currently active view in Revit.' This uses a specific verb ('Get') and resource ('currently active view'), distinguishing it from sibling tools like list_revit_views (which lists views) and get_revit_view (which likely retrieves a specific view by ID).

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—when you need info about the active view—but does not explicitly state when to use this tool versus alternatives. No exclusions or alternative suggestions are given, so guidance is only implicit. For a tool with clear sibling distinctions, explicit advice would elevate this to 5.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It only says 'get comprehensive information' without indicating whether the operation is read-only, what data is included, or any potential side effects. The description does not contradict annotations since there are none, but it fails to provide meaningful 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 a single, concise sentence that is easy to parse and front-loads the verb and resource. No unnecessary words are present, making it appropriately sized for a zero-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations, output schema, and parameter details, the description is too vague to be considered complete. It says 'comprehensive information' but does not specify what that includes, which is particularly problematic for an AI agent needing to decide whether to invoke this tool or a more specific sibling like list_revit_views or get_current_view_info.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics because there are none to document.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Get' with the resource 'current Revit model', clearly indicating this tool retrieves model information. It distinguishes itself from sibling tools like get_current_view_info and get_revit_status by focusing on the model rather than views or status, though 'comprehensive information' is somewhat vague about the exact scope.

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. There is no mention of preferred scenarios, prerequisites, or exclusions, leaving the agent to infer usage solely from the tool name and siblings.

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

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

With no annotations, the description carries full responsibility for behavioral disclosure. It goes beyond a simple status report by explicitly stating that it never returns the token itself, reports each side separately, and explains why (disagreeing settings cause auth failures). This adds significant behavioral context that is not inferred from the name or schema.

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 somewhat long but every sentence earns its place: it states the tool's purpose, lists the exact security questions, provides usage scenarios, clarifies a key limitation, and explains the rationale for separate reporting. The line breaks improve structure, keeping it readable despite the length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, no output schema), the description is quite complete. It covers what the tool does, when to use it, what it returns conceptually, and a key behavioral constraint. However, it does not describe the exact response format or any potential error conditions, which would be needed for a perfect score.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the schema covers 100% (empty properties). Per the rubric, no parameters gives a baseline of 4. The description adds no parameter-specific details, which is appropriate since there are none to describe.

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 reports the security posture of both halves of the bridge and lists the exact questions it answers. This specific verb+resource ('Report security posture') distinguishes it from sibling tools like get_revit_status, which is a general status check.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage scenarios: 'when the user asks whether the setup is safe, when a call was refused as unauthorized, or before rolling this out to more people.' It does not mention when not to use it or name alternative tools, so it falls short of a 5, but the guidance is clear and actionable.

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?

There are no annotations, so the description carries the full burden. It discloses that the tool checks liveness, implying a read-only operation, but does not mention side effects (likely none) or the exact nature of the response. Given the simplicity of a status check, this is adequate but not rich in behavioral detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no filler. Every word adds value, stating the exact purpose in a compact form.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (0 params, no output schema), but the description does not specify what the return value will be (e.g., a boolean or status message). For a status check, this is likely sufficient, but given no output schema, it would be more complete to briefly indicate the expected response format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the input schema is empty. The description does not need to explain parameters, and the schema coverage is trivially complete. Baseline for 0 params is 4, and no extra semantics are required.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Check if the Revit MCP API is active and responding' clearly states a specific verb ('check'), resource ('Revit MCP API'), and desired outcome (active/responding). It distinguishes from siblings like get_revit_security_status (security-specific) and get_revit_model_info (model info), making its purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives is given. However, the purpose is clear enough that an agent would infer it as a pre-flight health check before making other Revit API calls, but the description does not state this relationship or exclude any sibling 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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states the action without mentioning output format, side effects, required permissions, or whether the view must be active. This lack of detail fails the transparency burden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence that directly communicates the tool's purpose without any unnecessary words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema and no annotations, the description is too minimal. It does not clarify what the agent should expect in response (e.g., image data, file path) or any prerequisites, making it incomplete for reliable invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has a single required parameter 'view_name' with no description (0% coverage). The tool description does not elaborate on how to specify the view, such as exact name matching or case sensitivity, leaving parameter semantics entirely to the schema's minimal definition.

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 'Export a specific Revit view as an image' clearly states the action (export), the resource (a specific Revit view), and the output (an image). It distinguishes itself from sibling tools like list_revit_views by specifying the export behavior.

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 the tool is used when an image of a specific view is needed, but it does not explicitly mention prerequisites, alternatives, or when not to use it. Sibling tools like list_revit_views suggest a workflow, but no guidance is provided here.

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

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

With no annotations, the description fully carries the burden. It discloses several key behaviors: does NOT change the selection, there is no tool to set the selection, returns an empty list with total_selected 0 on no selection (successful, not error), and details limit truncation behavior while category_counts stays accurate. These are beyond what a simple read tool would imply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a purpose sentence, usage context, return summary, edge case, selection caveat, and an Args section. Every sentence earns its place—no filler. It is longer than average but appropriate for the tool's complexity and the lack of annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers return fields (element_id, name, category, type, level, category_counts, total_selected), edge cases (empty selection), and the relationship to other tools. Given there is no output schema, the description explains what the agent can expect from the response. It is complete for a read-only selection inspection 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?

Schema coverage is 0%, but the description provides rich meaning for both parameters. For 'limit', it explains it caps 'elements described in full' and that category_counts remains accurate for the whole selection. For 'include_parameters', it says it returns every readable instance parameter and warns it is 'Verbose - leave off unless actually needed'. This goes far 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 opens with 'Read what the user currently has selected in the Revit UI', providing a specific verb and resource. It clearly distinguishes this tool from siblings by stating it is 'the only way to find out' the user's selection, and contrasts with modify/delete tools that consume the returned element_ids.

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?

Explicitly states when to use the tool: whenever the user says 'these', 'the selected ones', or 'what I have highlighted'. It also frames it as the 'first call in a select-then-act workflow', giving clear context relative to modify_elements and delete_elements. The description also notes a non-use case (no selection returns empty list, not error).

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 disclosure. It reveals important behaviors: automatically finding installed versions, polling the pyRevit Routes health endpoint, and showing a worksharing dialog for central models. However, it does not mention return values, error handling, or behavior when a version is invalid, leaving some 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 and front-loaded. The first sentence states the core purpose, followed by concise behavioral notes, a paragraph on worksharing with an alternative, and a clear parameter list. Every sentence adds value without repetition or padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main workflow and parameters, but without an output schema it does not explain what the tool returns (e.g., success message, launched version, errors). It also omits edge cases like multiple installed versions or already-running instances. Given the tool's complexity and lack of structured metadata, some crucial information is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero descriptions for its parameters, so the description's Args section fully compensates. It explains file_path extensions (.rvt, .rfa, .rte), version as a year with 'Uses latest if omitted,' language as a code with examples, and timeout as seconds with a default of 120. This adds crucial 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 opens with 'Launch Revit on this machine, optionally opening a file,' which clearly states the action and resource. It further distinguishes itself from sibling tools like open_document by explaining the launch and readiness-check behavior, making the tool's specific role unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly directs users to 'Use the open_document tool after launch for more control over worksharing options like detach from central,' providing a clear alternative for a specific scenario. It also explains the automatic version discovery and readiness polling, giving context on when this tool is appropriate.

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

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

No annotations are provided, but the description discloses the return behavior: 'Returns each parameter with its type and a sample value.' The verb 'list' implies a read-only operation, and no side effects or prerequisites are mentioned. While it doesn't explicitly state 'read-only' or address edge cases, the transparent return format compensates for the absence of 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 three sentences plus an Args line, front-loaded with the core purpose, followed by return details and usage guidance. Every sentence adds value without 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 a single parameter and no output schema, the description fully covers what the tool does, what it returns, and when to use it. The explicit mention of return content (type and sample value) makes the tool's behavior complete for its simplicity.

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 only parameter, category_name, is explained with 'Revit category, e.g. "Walls", "Doors", "Rooms".' This adds concrete examples and domain context beyond the schema's bare string type, fully compensating for the 0% schema description coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'List' and identifies the resource as 'parameters available on elements of a category', clearly distinguishing it from sibling tools like list_family_categories or list_revit_views. It is unambiguous and immediately understandable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states 'Use this to find a valid parameter_name for color_splash, and to check what modify_elements can set on a category', naming specific sibling tools and concrete use cases. This provides clear guidance on when to use this tool versus alternatives.

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

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

With no annotations, the description fully discloses key behaviors: the return fields (family_name, type_name, category, activation status), the case-insensitive substring filtering, the limit/default, and the special meaning of an empty result. It also notes that placement fails on near-miss names, which is important context. No annotation contradiction exists.

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: a one-sentence primary purpose, followed by return field details and usage caveats, then parameter definitions. Every sentence contributes new, non-redundant information. It is long enough to be comprehensive yet remains tight and scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite lacking an output schema, the description clarifies the return format, edge cases (empty list), exclusions (system types), and integration with placement. For a list tool with two simple parameters, this covers all necessary context for correct invocation and interpretation.

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%, but the description provides full parameter semantics in the Args section: 'contains' is defined as a case-insensitive substring filter matched against family and type name, with omission behavior, and 'limit' is described as maximum results with a default of 50. This compensates completely 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 function: 'List loadable family types available in the current model.' It identifies the specific resource (family types) and scope (current model), and further distinguishes from system types, making it unambiguous. This separates it from sibling tools like list_family_categories or list_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?

Explicit guidance is given: 'Call this before place_family to get exact names - placement fails on a near-miss.' It also explains that an empty list is a successful answer, and clearly states what the tool does NOT list (system types) and where those are reported (error messages of create_line_based_element or create_surface_based_element), providing clear alternatives.

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

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

With no annotations provided, the description carries the full burden, and it delivers by stating the tool lists all categories and includes a count per category. It implies a read-only, non-mutating operation, though it does not explicitly state that there are no side effects or describe the response format beyond the count.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the primary function, and the second sentence adds valuable usage context without any redundancy. Every phrase earns 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?

This is a simple, parameterless listing tool. The description fully conveys its purpose, the output (all categories with counts), and practical use cases. The absence of an output schema is acceptable because the description states what is returned.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the baseline for such cases is 4. The description adds no parameter-specific information because none is needed; the schema already covers the empty parameter set completely.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'List' and the resource 'every family category in the model', clearly distinguishing it from sibling tools like list_families (lists families) and list_category_parameters. It also notes the count per category, adding precision.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool: 'before drilling into list_families' and for finding exact category spelling expected by tag_elements and color_splash. This provides clear context and names related tools, giving the agent actionable guidance on selecting this tool versus alternatives.

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

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

With no annotations, the description alone must disclose behavioral traits. It only states the action, not the return format, side effects, or safety profile. The read-only nature is implied by 'Get' but not stated explicitly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the verb and resource. Every word contributes to clarity with no 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 tool's simplicity (no parameters, no output schema), the description adequately conveys what it does and what it returns. It could mention the return format, but 'list of all levels' is sufficiently informative.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool accepts zero parameters, so there is no parameter ambiguity. The description confirms that the list is unfiltered, which is sufficient for a no-argument tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Get' and a clear resource 'all levels in the current Revit model', distinguishing it from sibling tools that list views, families, or categories.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly states the context (current Revit model) and implies the tool is for retrieving levels rather than other entities. However, it does not explicitly mention alternatives or when not to use it.

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

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

No annotations are provided, so the description must carry the behavioral disclosure. It does so by stating that it 'returns a list' and implying a read-only discovery operation. It does not elaborate on edge cases or performance, but it is sufficient for a simple list 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 three concise sentences, front-loading the purpose and return value, with no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This simple tool requires no inputs and has no output schema; the description explains what it returns and when to use it, making it complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has no parameters, and the description correctly avoids parameter information. Baseline is 4 for 0-parameter tools.

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 'Discover all Revit versions installed on this system' and specifies the return value as 'installed Revit versions with their executable paths,' making the tool's function unambiguous and distinct from 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 sentence 'Use this to check what's available before calling launch_revit' provides explicit usage context, though it does not explicitly mention alternatives or exclusions.

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

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

With no annotations, the description must disclose behavioral traits, but it only specifies that it lists exportable views. It does not clarify what 'exportable' means, what data is returned (names, IDs, types), whether a document must be open, or any potential side effects or limitations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that conveys the essential purpose without any filler. Every word contributes to understanding the tool's function.

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?

While the tool is simple (no params, no output schema), the description could still mention what fields appear in the returned list (e.g., view names, IDs, types). It also doesn't note that this is read-only or state prerequisites like an open Revit document. Missing these details leaves some ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema fully covers parameter information. The description correctly indicates a simple no-argument call; there is nothing missing.

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 'Get a list of all exportable views in the current Revit model' uses a specific verb ('Get a list') and resource ('exportable views') while scoping to the current model. It clearly distinguishes from siblings like get_revit_view (which likely returns a single view) and get_current_view_info.

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 alternative listing tools like list_levels or list_families, or when not to use it. The description is purely a statement of functionality with no contextual usage 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, the description carries the full burden and does so thoroughly. It discloses transactional behavior, per-element success/failure reporting, internal units, acceptance of true/false for Yes/No parameters, and that read-only/computed parameters fail explicitly. No annotation contradiction exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded. Every sentence serves a purpose, including the explicit non-goals and unit conventions, with no superfluous content. The Args section restates schema clearly.

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, absence of annotations, and no output schema, the description is remarkably complete. It covers prerequisites, parameter semantics, transaction atomicity, failure reporting, unit handling, and exclusions, which is more than enough for an agent to invoke 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?

Input schema has 0% coverage and no parameter descriptions, so the description must compensate. It does: element_ids must be non-empty, parameters is a name-to-value object with a concrete example and notes on units and value types. This is sufficient for an arbitrary-object parameter, though not exhaustively detailed.

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 starts with 'Set instance parameters on existing elements, by element id,' which is a specific verb+resource+scope. It clearly distinguishes this from create, delete, and type-parameter tools by explicitly stating what it does NOT do.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit usage guidance: 'Get element ids from get_selected_elements or get_current_view_elements first' and 'Use list_category_parameters to find out what parameter names a category actually has.' Also states exclusions (does not create elements, change type, edit type parameters) so the agent knows when not to use it.

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

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

With no annotations, the description carries the full burden for behavioral disclosure. It clearly explains the detach option's effect ('Preserves worksets but severs the link to the central model') and the audit option's purpose. It does not mention potential errors or side effects like closing the current document, but it provides meaningful behavioral context beyond a simple 'open' action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: a lead sentence stating the main purpose, one supporting line about workshared files, and a neatly formatted Args block with per-parameter details. Every word contributes value, no fluff or 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?

For an open-document tool with no output schema, the description covers essential context: file types, detach/audit behaviors, and prerequisite ('running Revit'). It omits edge-case behavior (e.g., what happens if the file is already open, or error handling) but is sufficiently complete for most usage scenarios.

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 no descriptions (0% coverage), but the description compensates with detailed explanations for each parameter: file_path (absolute path to specific extensions), detach (boolean, detaches from central), and audit (boolean, checks corruption). This goes well beyond what the schema provides, giving the agent complete understanding of each argument.

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: 'Open a Revit document file in the running Revit instance.' It specifies supported file extensions (.rvt, .rfa, .rte) and distinct options (detach, audit), making it easy to distinguish from sibling tools like close_document or save_document.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool (when needing to open a Revit file) but does not explicitly compare it to alternatives or mention exclusions. It notes 'in the running Revit instance,' which hints that Revit must be running, but it does not direct to launch_revit if it isn't. No explicit when-not-to-use instructions.

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

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

No annotations are provided, so the description carries the full burden. It discloses coordinate units (decimal feet), rotation units (degrees), error behavior (error lists available names), return value contents (id, actual location, applied/rejected properties), and a critical constraint (does NOT load families not already in the project). This is rich, behavior-disclosing 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 efficiently organized: a clear one-sentence purpose, usage guidance, key notes, return information, a constraint, and then a well-formatted Args list. Every sentence contributes value with no repetition or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (8 parameters, no output schema, no annotations), the description is comprehensive. It covers purpose, usage boundaries, units, error handling, return values, caveats, and parameter semantics. The user is fully equipped to decide when to use it and how to invoke it.

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. The Args list explains every parameter: family_name with example, type_name default, x/y/z units, rotation in degrees, level_name reference to list_levels, and properties with an example. This fully adds meaning beyond the bare schema titles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Place one instance of a loadable family at a point.' It also explicitly differentiates from sibling tools by naming create_line_based_element and create_surface_based_element for other element types, making the tool's scope unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear when-to-use context ('furniture, doors, windows, columns, equipment') and explicit alternatives for walls, beams, pipes, floors, and ceilings. It also tells the user to obtain family_name and type_name from list_families first and references list_levels, providing actionable guidance.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly explains the two behaviors (in-place save and Save As) and the condition that triggers each. It does not mention potential side effects like overwriting files or changing the active document path, but the core behavior is transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded, with the core purpose in the first sentence. The Args block repeats information already in the narrative, but it is brief and does not detract significantly from readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional parameter and no output schema, the description covers all essential behavior. It could mention file extensions or overwrite behavior, but the current level is sufficient for an agent to use it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides only a parameter name and type with no description, so the description must compensate. It clearly defines file_path as optional and explains its role in triggering Save As, adding meaningful context beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Save') and resource ('active Revit document'), clearly distinguishing it from sibling tools like open_document, close_document, or sync_with_central. It immediately communicates the tool's core 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 provides two explicit scenarios based on the presence of file_path: saving in place vs. Save As. This gives clear usage guidance, though it does not mention alternatives or conditions that would make this tool inappropriate.

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 explains the effects of each parameter (comment in the worksharing log, compact central, relinquish borrowed elements/worksets) and states the workshared-only precondition. However, it does not describe error behavior or what happens if the document is not workshared beyond the directive to use save_document.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured, with a clear opening statement and a neatly formatted Args section. Every sentence contributes useful information, with no redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema and annotations, the description covers the essential workflow, all parameters, and usage constraints. It is missing minor details such as return value or explicit error handling, but for a sync operation with this complexity, it is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has no parameter descriptions (0% coverage), but the description adds meaningful explanations for all three parameters: comment, compact, and relinquish_all, including the default value for relinquish_all. This fully compensates for the schema gap and provides clear semantic 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 explicitly states the action 'Synchronize the active workshared document with central' and clearly identifies the resource (workshared document). It distinguishes this tool from save_document by noting the workshared vs non-workshared distinction, which is a specific and helpful 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?

The description provides explicit usage guidance: it only works with workshared documents, and for non-workshared documents, it directs the user to save_document. This clearly states when to use the tool and when to use an alternative, offering strong contextual 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, the description carries the full burden and does so excellently. It discloses the active-view dependency, return value (count and skip reasons), the tag-family prerequisite, and detailed limitations (center placement, overlap, no cross-view, no family selection), providing full behavioral transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with the core purpose, followed by essential behavioral details and a clear 'Does NOT' list, then an Args section. Every sentence earns its place, and the overall length is appropriate for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no annotations and no output schema, the description covers everything the agent needs: what it does, return value, prerequisites, limitations, and parameter semantics. It also references a sibling tool for a related check, making it complete for this tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the 'Args' section fully compensates by explaining each parameter: category_name with examples and singular/plural handling, limit as a cap, skip_tagged with idempotency note, and leader. This adds substantial meaning beyond the schema's type/defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Place tags on all elements of one category in the ACTIVE view.' This clearly distinguishes it from sibling tools, and the 'Does NOT' list further clarifies scope, such as not tag across views or position tags intelligently.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly tells the agent to check get_current_view_info first if the active view matters, referencing a sibling tool. It also clarifies prerequisites (a loaded tag family) and what not to retry, plus the 'Does NOT' list implicitly signals when not to use this tool.

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