adcs_info

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

No annotations are present, so the description must carry the burden. It states it is a query operation and mentions pagination parameters, but does not explicitly disclose side effects, authentication needs, or return format. The read-only nature is implied but not stated.

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 long but well-structured with a purpose statement up front and a clear bulleted list of info_type options. Every line adds necessary detail; it is not padded, though it could be slightly more concise by grouping similar options.

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 absence of an output schema, the description compensates by explaining what each info_type returns (properties, controllers, hierarchy, etc.) and the pagination parameters. It lacks explicit return structure, but for a query tool with many options, this is reasonably complete.

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 description significantly enriches the parameter definitions by explaining exactly what object_id means (template ID or CA ID depending on info_type), listing all possible info_type values, and defining limit and skip for pagination. This far exceeds the sparse schema.

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 queries AD Certificate Services data from BloodHound, with a specific resource and action. It distinguishes itself from sibling tools by focusing on ADCS-specific info types rather than general entity info.

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?

Provides clear context on how object_id relates to info_type and enumerates all valid info_type values with explanations. Does not explicitly mention alternatives or when to avoid, but the exhaustive list gives strong usage guidance.

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