FogBugz

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

The description adds significant behavioral context beyond what annotations provide. While annotations indicate destructiveHint=true and readOnlyHint=false, the description explicitly warns: 'WARNING: Can execute any API command the configured key permits, including destructive operations (delete, edit users, bulk modify).' This provides concrete examples of destructive operations and clarifies the broad permission scope, which annotations alone don't specify.

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 efficiently structured with zero waste: it opens with the core purpose, immediately provides critical warnings, gives usage guidelines, and concludes with concrete examples. Every sentence serves a distinct purpose, and the information is appropriately front-loaded with the most important warnings first.

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 as a generic API escape hatch with destructive capabilities and no output schema, the description provides excellent contextual completeness. It covers purpose, warnings, usage boundaries, and examples, compensating for the lack of output schema by illustrating potential use cases. The combination with annotations creates a comprehensive understanding.

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 100% schema description coverage, the baseline is 3. The description adds some value by providing examples of cmd values (listProjects, listCategories, search) and params usage, but doesn't fundamentally enhance understanding beyond what's already documented in the schema's parameter 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's purpose as a 'generic XML API escape-hatch for FogBugz commands not covered by dedicated tools,' specifying both the verb (execute API commands) and resource (FogBugz). It explicitly distinguishes this from sibling tools by mentioning 'commands not covered by dedicated tools' and listing specific sibling tools in examples.

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 explicit guidance on when to use this tool vs alternatives: 'Prefer specific tools when available; use this only when no dedicated tool fits the need.' It includes examples of commands that might be used with this tool, reinforcing the boundary between dedicated and generic tools.

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