Get Dn

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

The readOnlyHint annotation already covers the safety profile, so the description's job is to add resolution semantics — and it does: it is idempotent ('Returns the value unchanged if it already looks like a DN') and fails soft ('Returns None if not found'). These are non-obvious behaviors the annotation does not convey. It doesn't explain whether the lookup is exact-match or a search under base/domain, which is the main remaining gap.

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?

Three short sentences, front-loaded with the core action, followed by edge-case behavior, then routing advice. Every sentence adds information and nothing is padded.

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?

An output schema exists, so return-value documentation is not required, and the description correctly notes the None case. However, for an LDAP tool where 'base' and 'domain' determine which naming context is searched, omitting both leaves the agent without enough to call it confidently in multi-domain setups.

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 description coverage is 0%, so the description must carry all meaning for the three parameters. It clarifies 'entry' meaningfully (sAMAccountName or DN), but 'base' and 'domain' are never mentioned, leaving two parameters with no semantic information anywhere.

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 states a specific verb and resource: 'Resolve a sAMAccountName (or DN) to a distinguished name (DN).' It also distinguishes itself from the sibling get_by_dn by positioning itself as the pre-step that produces a DN. An agent can tell exactly what this returns without opening the schema.

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 explicit downstream usage ('Handy before get_by_dn or get_ou_contents'), which tells the agent when to reach for it relative to named siblings. It does not state when not to use it, nor how it relates to search_ldap or the find_* tools, so it falls short of a full 5.

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