Find Computers

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

Annotations only declare readOnlyHint, and the description adds real behavioral context on top: matching semantics (AND), wildcard support, the effect of exclude_domain_controllers, and the subtree restriction from base. That is exactly the value-add beyond structured fields this dimension rewards.

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?

Four tight sentences, front-loaded with the core capability, then progressively detail matching semantics, the boolean flag, and the subtree scope. No redundant restatement and no wasted prose.

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 7-param read-only search with an output schema (so return shape needs no explanation), the description covers the mechanics an agent needs to build a correct query: AND semantics, wildcards, DC exclusion, and subtree scoping. The minor limit/domain omissions do not block correct invocation.

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?

With 0% schema description coverage, the description must carry parameter meaning, and it does for most: it translates name/dns/os to their AD attributes, defines base as a DN/OU, states the wildcard syntax, and explains the boolean flag. However, it never documents limit (default 100) or domain, leaving truncation/domain-selection behavior to inference.

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 a specific verb and resource ('Find AD computers') and then maps each filter argument to the underlying AD attribute (cn, dNSHostName, operatingSystem), which lets an agent distinguish this search tool from single-object siblings like get_computer and from narrower searches like find_stale_computers.

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 explains how to combine criteria (ANDed), that wildcards are supported, how to exclude domain controllers, and how to scope to a subtree — clear operational guidance. It stops short of explicit when-to-use/when-not guidance against siblings such as get_computer or find_stale_computers, so it lands at 4 rather than 5.

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