Summarize model contents

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

Beyond the readOnlyHint and destructiveHint annotations, the description discloses cost/safety behavior ('cheap and safe', 'can crash Archicad'), conditional refusal, scope semantics ('whole-plan' vs 'model-elements-only'), and a guarantee that by_type is always returned. This is rich, non-obvious 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 dense but every clause adds value: default behavior, cost warning, output semantics, and coverage caveat. It is front-loaded with the core verb and resource, though the later sentences are long and use parenthesis-heavy asides that reduce 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 read-only aggregation tool with an output schema, the essential behavioral and safety caveats are covered, and the coverage field semantics are explained. The only material omission is port, especially because the input schema provides no description for 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?

include_layer_story is well explained with consequences and default context, and the description clarifies output behavior for by_type and coverage. However, schema coverage is 0% and the port parameter is never described, leaving a meaningful gap for an agent deciding whether to set it.

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

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

Description opens with 'Aggregate element counts', a specific verb and resource, and immediately distinguishes itself from element-level tools by stating 'Counts only, never element data.' This clearly separates it from siblings like get_element_data and query_elements.

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

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

It gives clear context: the default call is 'cheap and safe', and the optional include_layer_story flag is described as potentially expensive and refused on large models. It does not explicitly name alternative sibling tools or state when to prefer them, so it falls just 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.