ai_element_filter

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates that the tool is read-only ('retrieve detailed element information'), includes a performance note about maxElements, and highlights nuances like furniture category ambiguity. However, it does not explicitly state the return format or error behavior, which would be valuable, but the provided details are substantial.

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 moderately long (about 150 words) but well-structured: a clear definition, capability breakdown, and a practical usage example. The step-by-step example is valuable for agents but adds length; still, every section contributes to understanding. It is not overly verbose, but the example could be shortened slightly, so it warrants a 4 rather than 5.

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 query tool with no output schema, the description provides a good overall picture: it explains filtering options, performance considerations, and the intended workflow. It does not specify the exact structure of the returned data, but the example implies the AI will receive 'detailed information' for further processing. Given the richness of the schema and the illustrative steps, the description is fairly complete, though a bit more detail on output format would push it to 5.

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 100% description coverage, so the baseline is 3. The tool description adds an example of using 'filterCategory' and 'includeInstances' and notes that multiple filters can be combined, reinforcing schema semantics. However, it does not introduce new parameter meanings beyond what the schema already provides, so a score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'An intelligent Revit element querying tool designed specifically for AI assistants to retrieve detailed element information from Revit projects.' It specifies the verb 'retrieve' and resource 'element information', and the example workflow ('Find all walls taller than 5m') further clarifies its role. It distinguishes itself from sibling tools like get_current_view_elements and get_selected_elements by focusing on filtered retrieval based on criteria.

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

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

The description provides a concrete example of when to use the tool: when a user asks to find elements matching specific criteria, the AI should call this tool with appropriate filters. It implies the tool is the primary querying mechanism for element data, but it does not explicitly mention alternatives or exclusion cases. This is clear context without exclusions, so it aligns with a score of 4.

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