adtk

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

With no annotations provided, the description carries the full burden of behavioral disclosure. While it lists actions, it doesn't describe what each action does, their side effects, authentication requirements, rate limits, or error conditions. 'Manage' is vague about whether actions are read-only or mutative (create_branch/create_tag suggest mutations). The description provides minimal behavioral context beyond naming actions.

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 appropriately concise - a single sentence stating the purpose followed by a comma-separated list of actions. No wasted words, though the action list could be better structured (e.g., grouping read vs write actions). The purpose is front-loaded, which is good.

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 complex tool with 12 parameters, multiple actions (including mutations like create_branch), no annotations, and no output schema, the description is inadequate. It doesn't explain what the tool returns, how actions differ, error handling, or authentication needs. The agent would struggle to use this tool correctly without significant trial and error.

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 schema has 100% description coverage, so parameters are well-documented in the structured schema. The description adds no parameter semantics beyond what's already in the schema descriptions. It lists action names but doesn't explain what each action does or how parameters relate to them. Baseline 3 is appropriate when schema does the heavy lifting.

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 manages Azure DevOps Git repositories and lists specific actions. It provides a specific verb ('manage') and resource ('Azure DevOps Git repositories'), but doesn't distinguish this from sibling tools like manage_projects or manage_pull_requests that also manage Azure DevOps resources.

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 no guidance on when to use this tool versus alternatives. There's no mention of prerequisites, when certain actions are appropriate, or how this tool relates to sibling tools like manage_projects or manage_pull_requests. The list of actions implies scope but doesn't provide usage context.

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