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

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds behavioral detail: it returns an index, declarations, or a named type depending on arguments, and notes the 🔒 tier marker. It does not contradict annotations. Minor gap: it does not specify behavior if both domain and type are provided, which is a small transparency shortfall.

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 efficient and well-structured. It opens with the purpose, then quickly explains the three invocation modes, each in a concise clause. Every sentence adds value, and the tier marker note is front-loaded. 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?

Given the tool's complexity (three modes) and lack of output schema, the description covers the key behaviors: what each mode returns, the tier marker, and the API's calling convention. It does not cover error cases or ambiguous input (both domain and type), but for a reference tool, it is nearly complete. The sibling context is also addressed by mentioning query and execute scripts.

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 100%, so baseline is 3. The description adds semantic meaning beyond the schema: it explains that domain yields TypeScript declarations and type yields a named type, and that no args yields the index. This clarifies how each parameter affects the response, going beyond the schema's basic string 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 is a reference for the foundry.* API, used in query and execute scripts. It specifies three distinct invocation modes (no args, domain, type) and what each returns, distinguishing it from the execution-focused sibling tools. The verb 'reference' and resource are explicit, and it is not a tautology.

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 says to 'Read the domain declarations before writing a script,' which implies using this tool before writing code with the API. It explains how to invoke it with domain or type, giving clear context on when to use it. It does not explicitly mention alternatives or exclusions, but the purpose inherently separates it from execute/query tools.

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