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

With no annotations provided, the description carries the full burden and delivers: APS scopes (data:read, viewables:read), rate limits, error responses with specific status codes and remedies, and side effects ('Read-only. Idempotent.'). This richly discloses behavior, going far beyond minimal mutation safety to include operational expectations.

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 uses labeled sections (When to use, When NOT to use, APS scopes, Rate limits, Errors, Side effects) that front-load the most important information. While it is longer than average, every sentence provides actionable detail 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 simple one-parameter list operation, the description is complete: it explains what will be returned (sheet number + name), when to use it, how to avoid misusing it, auth scopes, errors, and side effects. No output schema exists, but the description sufficiently covers return values. The absence of pagination notes is a minor gap but does not undermine usability for an AI agent.

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

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

The input schema already fully documents model_id with pattern, examples, and description (coverage 100%). The tool description adds context about the URN being for a 'translated Revit model' but does not introduce new parameter-level syntax or constraints beyond the schema. Thus a baseline 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 opens with 'Enumerate the drawing sheets (title blocks with sheet number + sheet name like 'A-101: First Floor Plan')' which precisely identifies the action and resource. It also explicitly contrasts with sibling tool revit_get_views by stating 'this returns only 2D sheet entries', making the purpose unambiguous and well-differentiated.

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 'When to use' and 'When NOT to use' sections, naming the exact alternative tool (revit_get_views) for model views. This is the highest level of usage guidance, clearly stating conditions for invocation and exclusions.

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