pyrevit-mcp

by mk92at

Overview Schema Related Servers Score Discussions

Python

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation4/5
Most tools have clearly distinct purposes (selection, views, levels, parameters, graphics), but get_elements and find_elements overlap since both retrieve elements by category; find_elements adds filtering but the simpler get_elements could be confusingly similar. override_graphics and color_by_parameter both apply colors, though one is manual and the other parameter-driven.
Naming Consistency3/5
The naming convention is mixed: many query tools use get_ (get_elements, get_views, get_model_info), setters use set_ (set_selection, set_parameter), but there are also list_parameters, find_elements, override_graphics, isolate_elements, reset_view, and export_image which deviate from a strict verb_object pattern. It's readable but not fully consistent.
Tool Count4/5
With 21 tools, the server is slightly above the typically ideal 3-15 range, but the breadth is justified by Revit's complexity, covering model info, element queries, parameter editing, view management, graphics overrides, and save/export. No tool feels redundant enough to be cut.
Completeness3/5
The tool surface covers a wide range of operations (query, selection, view control, parameter editing, graphics, warnings, save), but it notably lacks element creation or deletion, which are core lifecycle operations in Revit. Some gaps like geometry access are absent, but agents can work around them using the existing parameters and element queries.
Average 4.1/5 across 21 of 21 tools scored. Lowest: 3.1/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 14 commits in the last 12 weeks
- Last stable release on August 12, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits but only says 'get'. It does not mention read-only nature explicitly, error handling, return format, or side effects. For a getter with no annotation context, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, with a clear single-sentence purpose and an argument list. It is easy to scan and free of fluff, though the Args section redundantly mirrors schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter getter, the description is minimally adequate but lacks any mention of output shape, behavior for invalid IDs, or what 'all properties' includes. The absence of an output schema and annotations increases the burden, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description repeats the parameter name and type ('integer ID') without adding meaningful context like bounds, defaults, or relationship to the element. The schema already provides the type and title, so the description adds little value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets all properties/parameters of a specific Revit element by ID. It names the specific resource (Revit element) and the action (get), distinguishing it from siblings like get_elements and list_parameters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. Sibling tools like list_parameters or get_elements could be confused with this one, but the description gives no differentiation or preferred context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, and the description carries full responsibility for behavioral disclosure. It mentions the active view but does not reveal whether the color override is permanent, reversible, or how it interacts with existing overrides. It also fails to mention any side effects or view requirements beyond 'active'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence purpose followed by an Args block. No unnecessary words, and the parameter formatting is clean and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The purpose and parameters are adequately described, but the description lacks usage context, behavioral nuances, and any guidance on alternatives. This is a simple tool, but without annotations or output schema, more detail on expected side effects would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates well by detailing the allowed color names and hex format, and clarifying that element_ids are integers. This adds meaningful semantic information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Colour elements in the active Revit view so they stand out visually.' It uses a specific verb and resource (elements in active view), but does not explicitly differentiate from sibling tools like color_by_parameter or isolate_elements, which serve related purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. The description does not mention any use cases, prerequisites, or exclusions, leaving the agent without context for tool selection among siblings like color_by_parameter or isolate_elements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden, but it only states the basic operation. It does not disclose return format, error behavior (e.g., invalid category), whether results are limited to visible elements, or any side effects. The limit parameter is already in the schema, so no new behavioral context is added.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized: one opening sentence states the action and scope, followed by a concise Args section that documents both parameters. Every sentence is useful and there is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with 2 parameters, and the description covers the essential 'what' and 'how'. However, there is no output schema and the description does not explain what the returned elements look like (e.g., IDs, names) or what happens when a category does not exist. Given the absence of annotations and output schema, more completeness would be expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only titles and a default, with zero property descriptions. The description compensates by explaining both parameters: category includes concrete examples ('Walls', 'Doors', 'Rooms', 'Floors') and limit clarifies its purpose and default. This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear action: 'Get elements from the active Revit model by category name.' It specifies the resource (active Revit model), the method (by category), and distinguishes from siblings like get_selection (selected elements) and get_categories (categories).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as find_elements or get_selection. There are no explicit use-case constraints, prerequisites, or exclusions. The description implies a basic query operation but does not help the agent choose among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the burden of behavioral disclosure. It does not state whether the tool is read-only, what it returns (e.g., boolean and document name), or how it handles the case where Revit is not running. Minimal behavioral context is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that directly conveys the tool's purpose without any unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 provides a basic understanding. However, it lacks details about return values, error behavior, or the format of the open document information, making it minimally adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so there is nothing to explain. The baseline for zero parameters is 4, and the description adds no conflicting or additional parameter-related information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: checking if Revit is running and identifying the open document. It uses specific verbs ('check', 'open') and distinguishes itself from sibling tools that query categories, selection, or other data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. The description only states what it does, not when it should be invoked or whether it is a prerequisite for other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It lists the data fields returned (title, path, project information, active view, element counts), which gives insight into output content. Yet it does not explicitly state that the operation is read-only or side-effect-free, nor mention any performance characteristics or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the tool's purpose and then enumerates its key data components. There is no redundancy or unnecessary filler, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter overview tool without an output schema, the description covers the major return fields and gives a clear sense of what information is available. It could be slightly more specific about which 'common categories' are counted, but overall it is sufficient for basic tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description is not required to explain input semantics. The baseline score of 4 applies, and the description appropriately focuses on the output, which is the main relevant aspect for selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides an 'Overview of the open model' and lists the included components (title, path, project information, active view, element counts). This distinguishes it from sibling tools that focus on narrower aspects like categories or levels, though it lacks an explicit action verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a general model overview is needed, and the listed content suggests it is a catch-all tool compared to more specific siblings. However, it does not explicitly state when not to use it or name alternatives, leaving the decision partially to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 merely states the purpose without explaining the return format (e.g., element IDs, objects), potential side effects, or that it is a read-only operation. The lack of any detail beyond the one-line purpose leaves significant behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the action and resource. Every word earns its place, with no unnecessary filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with no parameters and no output schema, so the description must convey the return value. While 'Get the elements' conveys the concept, it does not specify the data format (e.g., list of IDs, references). This is adequate but leaves a notable gap about what the agent will receive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and an empty schema (100% coverage). With no parameters to describe, the baseline is 4. The description does not need to add parameter information; it correctly focuses on the tool's action.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action (get) and resource (currently selected elements in the Revit window). It distinguishes itself from siblings like set_selection (which modifies selection) and get_categories (which retrieves categories, not selection).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: call this when you need the current selection in Revit. However, it does not explicitly state when not to use it or mention alternatives such as get_elements for broader element retrieval. No exclusions or comparative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the empty-list-clears behavior, which is useful. Yet it does not explicitly state that the selection is replaced wholesale, nor does it mention error behavior or return value. Some transparency but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose, and includes an important edge case. No redundancy or irrelevant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema. The description covers core selection behavior, the empty-list case, and parameter purpose. A minor gap is not explicitly saying 'replaces current selection,' but overall this is nearly complete for such a straightforward tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 description restates parameter name and type ('Integer IDs') which duplicates schema info, and adds only minimal context that these are elements to select—essentially a rewording of the title 'Element Ids'. It fails to explain the nature of element IDs in the Revit domain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb+resource: 'Select elements in the Revit window.' This distinguishes it from siblings like get_selection (which retrieves) and isolate_elements (which changes visibility). The added note about empty list clearing selection further clarifies scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied: use when needing to change the current selection. However, there is no explicit comparison to alternatives or exclusions, leaving the agent to infer when this tool is appropriate relative to sibling tools like isolate_elements or override_graphics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It only states the action without mentioning any side effects, prerequisites beyond view_id, or impact on the Revit document or UI state (e.g., whether the previous view is closed, if selection changes, or if any model modifications occur). The description adds no behavioral detail beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise, using a single sentence to state the purpose and a brief Args section for the parameter. No unnecessary words or repetition; every element earns its place. The structure is clean and front-loaded, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, no nested objects), the description is adequately complete. It specifies the action and the parameter's origin. However, it could be more complete by mentioning what happens after switching (e.g., return value or impact on the UI), but the absence of an output schema and the straightforward nature of the operation make this a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the schema only defines view_id as an integer with no description, the tool description adds crucial meaning: 'Id of the view to open, as returned by get_views.' This tells the agent exactly where to obtain a valid view_id, significantly compensating for the 0% schema coverage. The description adds value beyond the schema's bare type definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Switch the Revit window to another view.' This uses a specific verb ('Switch') and resource ('view'), and it distinguishes itself from sibling tools like 'get_views' (lists views) and 'reset_view' (resets view) by specifying the action of changing the active view.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by noting that view_id is 'as returned by get_views,' which indicates a prerequisite to call get_views first. However, it does not explicitly state when to use this tool vs. alternatives or provide any exclusions or contextual scenarios. This is clear but lacks the explicit guidance seen in higher-scoring examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 that this is a read operation ('Read from a sample element') and describes the data returned. However, it does not explicitly state that no modifications occur, nor does it explain how the sample is chosen or what happens if the category is empty or invalid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact (about 50 words), with a clear purpose sentence, a usage sentence, and a concise parameter explanation. There is no redundancy; every sentence adds value and it is well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only one parameter, no output schema, and no annotations, the description must be self-sufficient. It covers the core purpose, usage, parameter definition, and expected return fields. However, it omits edge-case behavior such as empty categories or multiple element types, which is a notable gap for an agent relying solely on this text.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero description coverage for the category parameter, but the description compensates with an 'Args:' section defining it as 'Revit category name, e.g. Doors' and giving a concrete example. This is sufficient for an agent to supply the parameter correctly, though it lacks details like case sensitivity or exact matching rules.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List which parameters a category's elements have' – a specific verb and resource, and it enumerates the returned fields (name, instance/type scope, data type, writable). This clearly distinguishes it from sibling tools like get_element_properties or set_parameters. The phrase 'Read from a sample element' further clarifies the mechanism.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states 'Use this before filtering or writing when unsure of exact names,' giving a clear when-to-use. However, it does not mention when not to use it or contrast it with alternatives like get_element_properties, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for side effects. It discloses that elements without a value are gray and that a legend is returned, but it does not mention whether the coloring persists, how it interacts with existing overrides, or whether it applies to all views. More disclosure is needed 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well structured: a two-sentence functional overview followed by a tidy Args list. Every sentence adds value, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description is the only source for return values. It mentions 'get the legend back' but not the legend's format or contents. It also omits side-effect scope (e.g., active view, persistence) and prerequisites. While the core purpose is clear, these gaps leave the description incomplete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions (0% coverage), but the description's Args section provides meaningful explanations for all three parameters: examples ('Doors', 'Fire Rating'), type hints ('instance or type'), and optionality ('Omit for all levels'). This fully compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description is highly specific: 'Colour every element of a category by its value of one parameter, one colour per distinct value, and get the legend back.' This clearly identifies the action, resource, and distinct behavior (legend, gray for no value), setting it apart from siblings like override_graphics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case: 'Great for visual QA, e.g. doors by Fire Rating.' This gives the agent context for when to invoke the tool, though it does not explicitly mention when not to use it or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It correctly implies a read-only operation via 'List', but does not describe return format, error behavior, or any side effects. The 'current model' scope is useful, but more detail would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences that immediately state the action and usage context. There is no wasted wording, making it highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter list tool, the description adequately explains what it returns and when to use it. Without an output schema, some might expect details on category format, but the simplicity of the operation makes it sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so parameter explanations are unnecessary. Per the rubric, a baseline of 4 applies, and the description does not need to compensate for missing parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with the resource 'element category' and scope 'current model', clearly distinguishing it from sibling tools like get_elements and get_element_properties. This unambiguously states 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes when to use this tool: 'Use this when a category name was rejected.' It provides clear context but does not mention when not to use it or name alternative 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.
Behavior3/5
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 the core behavior—undoing overrides and isolation—but lacks details on scope (e.g., does it affect all overrides or only certain types?) and does not mention side effects or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the action and resource. It contains no redundant information and is easily scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool, the description adequately explains the purpose and outcome. It does not explain return values or error conditions, but these are not required given the tool's simplicity and lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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. There is nothing for the description to add about parameter meaning; the empty schema confirms no arguments are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Undo' with a clear resource: 'colour overrides and temporary isolation in the active Revit view'. It clearly differentiates from siblings like override_graphics and isolate_elements by describing the opposite operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage after applying color overrides or temporary isolation, and clarifies the effect of restoring normal appearance. However, it does not explicitly state when not to use it or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It states the output (file path) and width range, but does not disclose file creation details, error conditions, or whether the view must be set. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded, and directly states purpose and parameter info without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no annotations or output schema, the description covers the core function and parameter. It lacks details on return value format and behavior on errors, but is sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful parameter documentation: width is defined as image width in pixels with a range and default, which is not present in the schema. For the single parameter, this fully compensates for zero schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool exports the active Revit view as a PNG image and returns the file path, using a specific verb and resource. It distinguishes itself from sibling tools by being the only image-export tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case: when a PNG of the active view is needed. It does not explicitly mention alternatives, but no sibling tool serves this purpose, so the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden. It discloses what the tool returns (grouped warnings with counts and sample element ids) and implies a read-only operation via the name 'get_warnings' and 'reports,' but it does not explicitly state side effects or permissions. While safe, this leaves some ambiguity for an AI agent, hence a mid-range score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences deliver the core purpose and a practical usage tip. Every word earns its place—no fluff, no repetition. The description is front-loaded with the key information and remains highly readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description must explain return values, and it does: grouped by type with counts and sample element ids. It also covers the primary use case. For a zero-parameter tool, this is complete and sufficient 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.
Parameters4/5
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 with 100% coverage. Per the rubric, zero parameters receive a baseline of 4. The description adds relevant meaning about the output structure (grouping, counts, sample ids) without needing to explain parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'every warning Revit currently reports, grouped by type with counts and sample element ids.' It uses specific terms (warning, grouped, counts, element ids) that distinguish it from sibling tools like get_elements or get_categories. The function is unambiguous and resource-specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this is a 'Model health check' and suggests a specific follow-up action ('Use override_graphics on the element_ids to show a warning group in the model'). However, it does not explicitly mention when not to use or describe alternatives, so it misses the 'when-not/alternatives' bar for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey safety and behavior. 'List' implies a read-only operation, and the mention of sorting bottom-to-top is additional behavioral detail. It doesn't discuss return format or edge cases, but for a simple listing tool, it is sufficiently transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that conveys all essential information without waste. Each word earns its place, and the structure is ideal for an agent to quickly understand the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no annotations, and no output schema, the description covers the core behavior: it lists all levels and their elevations, sorted. It could possibly mention the output structure (e.g., array of objects), but for a straightforward tool, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100% (empty schema). With no parameters to explain, the baseline of 4 applies, and the description adds value by stating what is returned (levels with elevations) and the ordering.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('all levels in the model'), and adds details about elevations and sorting. This clearly distinguishes it from siblings like get_categories (which lists categories) and other list-like tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use it (whenever levels are needed) and provides context (all levels, sorted). It doesn't explicitly mention alternatives or exclusions, but the context is unambiguous for a simple listing tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that the active view is marked, which is a helpful output behavior. The verb 'List' signals a read-only operation, though it does not explicitly state that no modifications occur, which would warrant a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the primary action ('List the views'). Every word adds value—the view types and marking of active view are relevant and non-redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no parameters, no output schema), the description fully explains what is returned (views with ids, active marked) and covers the essential context. It is complete for an agent to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100%. Per the rubric, the baseline for 0 parameters is 4. The description adds no parameter-specific details because none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('views in the model') and enumerates view types ('plans, sections, 3D, schedules'), making it unambiguous. It clearly distinguishes from sibling tools like set_active_view (which sets) and reset_view (which resets).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: this tool retrieves a list of views with IDs and marks the active view. While it does not explicitly mention alternatives or when-not to use, the purpose strongly implies it is for reading view information. No exclusions or conflicting guidance are present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that saves are persistent, that workshared models sync with central, and that unsaved changes are lost on restart. This goes beyond the name and provides useful context, though it stops short of describing failure modes or confirmation prompts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, and every clause adds value. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless save tool with no output schema, the description covers what it does, when to use it, and why it matters. It is complete for this level of complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100% (the schema is empty). The baseline for no parameters is 4, and the description adds no parameter-specific detail since none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool saves the model and distinguishes between standard save and synchronize-with-central for workshared models. This is specific and differentiates from sibling tools that handle selections, graphics, and parameters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly advises saving after important edits to avoid data loss, providing a clear when-to-use condition. It does not mention alternatives or when-not-to-use, but no sibling tools offer save-like functionality, so the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the write operation, transaction handling, type parameter fallback, side effects on all instances, response contents (scope, instances_affected, warning), and unit conventions for numeric values. This is excellent disclosure beyond simple operation description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, front-loaded with a clear summary, followed by important behavioral context and an Args block. Each sentence provides necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations or output schema, the description covers most essential behavior: transaction, fallback, side effects, units, and partial response format. It does not explicitly state the normal success response or error cases, which are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions for parameters (0% coverage), but the description's Args section clarifies element_id as an integer ID, parameter_name as exact name from get_element_properties, and value with unit caveats and advice for writing text parameters. This fully compensates for the schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Set a parameter value on a Revit element' and describes the transaction lifecycle. It distinguishes from sibling tools by focusing on a single parameter write, though it doesn't explicitly contrast with set_parameters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the behavior of falling back to type parameters and warns about the consequences, but it does not explicitly state when to use this tool versus alternatives like set_parameters. The guidance about warning the user is useful, but it lacks explicit alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It clearly says the action is temporary and hides everything except the specified elements. It could mention that it replaces any existing isolation state or how to undo it, but it provides the essential behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence followed by a minimal Args section. No wasted words, front-loaded with the purpose. It is an appropriate size for a one-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description is complete. It explains what happens, the scope (active view), and the parameter semantics. It does not leave obvious gaps for the agent to select or invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. The Args line explains that element_ids are 'Integer IDs of the elements to keep visible,' adding meaningful semantics beyond the raw schema fields (title and type). This fully clarifies the parameter role.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Temporarily hide everything except these elements') and the specific resource ('in the active Revit view'). It is a specific verb plus resource and scope, and distinguishes from siblings like reset_view and override_graphics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context ('in the active Revit view') and implies a use case (isolating elements). It does not explicitly mention alternatives or when not to use it, but the purpose is obvious enough relative to the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses transaction behavior (one transaction, one round trip, single undo entry), ordering ('applied in order'), and failure handling ('failed items are reported per item, the rest are still written'). It doesn't mention permissions or side effects, but for a parameter setting tool this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states the core benefit, the second gives a clear usage preference, and the Args block is concise. Every sentence earns its place with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully explains how to construct the assignments and the execution semantics, and it distinguishes from the sibling set_parameter. It doesn't explicitly describe the return value format beyond 'reported per item', which is a minor gap given there's no output schema, but it's otherwise complete for a tool with one parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines 'assignments' as an array of generic objects with no item structure, so the description's Args block is essential. It defines the exact structure (element_id int, parameter_name str, value str), ordering, and failure semantics, fully compensating for the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Set many parameter values in ONE Revit transaction', specifying the verb ('Set'), the resource ('parameter values'), and the scope (multiple in one transaction). It also distinguishes this from the sibling tool set_parameter by explicitly saying 'Always prefer this over calling set_parameter in a loop.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit usage guidance: 'Always prefer this over calling set_parameter in a loop' and explains why (one round trip, single undo entry). This tells the agent exactly when to choose this tool over its alternative, though it doesn't mention when to prefer set_parameter for a single parameter, which is implied but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it delivers: it explains unit handling ('comparisons are against the DISPLAY value in project units' with an example), the behavior of 'empty' operators, the meaning of 'matched' when the limit caps results, and that values return in project units. This goes well beyond basic read/write hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an opening summary and an Args block. Every sentence adds value: the 'Prefer this' line is actionable, and parameter details are concise but complete. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 params, no output schema), the description covers all key aspects: filtering logic, unit conversions, return behavior (include_params), limit behavior, and true match count. It gives the agent enough to invoke the tool correctly and interpret results, even without a formal output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so all parameter meaning must come from the description. It explains every parameter: category (with localized name support), level, operator (enumerating valid values and special semantics for empty/not_empty), value (unit conversion note), include_params, and limit (default and matched field). This is exemplary parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Find elements of a category, optionally filtered by level and by a parameter value, and return the parameters you ask for in the same call.' It uses a specific verb ('find'), names the resource ('elements'), and distinguishes it from siblings like get_elements and get_element_properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Prefer this over calling get_elements and then get_element_properties per element.' This directly tells the agent when to use this tool versus alternatives, and outlines optional filters (level, parameter) that define its scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![pyrevit-mcp MCP server](https://glama.ai/mcp/servers/mk92at/pyrevit-mcp/badges/card.svg)](https://glama.ai/mcp/servers/mk92at/pyrevit-mcp)

Score Badge

Copy to your README.md:

[![pyrevit-mcp MCP server](https://glama.ai/mcp/servers/mk92at/pyrevit-mcp/badges/score.svg)](https://glama.ai/mcp/servers/mk92at/pyrevit-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mk92at/pyrevit-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server