add_alias

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

No annotations are provided, so the description carries the burden. It discloses the 'Globally unique' constraint, which is behavioral. However, it doesn't state what happens on conflict (error? overwrite?), whether aliases are reversible/removable, or any side effects on already-resolved references. With zero annotations, more disclosure would be expected (e.g., does adding an alias affect existing resolve calls?).

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?

Two sentences plus an example — compact and front-loaded with the primary purpose first. The example is essential and earns its place by clarifying parameter roles. Minor waste: no heading/labels separate example from description, but it reads clearly. Could arguably be even tighter.

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 simple 2-param tool with an output schema present, the description is reasonably complete. The example demonstrates a realistic usage pattern tying in resolve_ref. Gaps: no mention of error handling for non-existent refs or existing aliases, and no global-uniqueness behavior details beyond the statement. But given the low complexity and that the output schema exists, the coverage is adequate.

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 compensate, and it does via the example. The example clarifies that 'ref' is the target entity (component:api-gateway) and 'alias' is the short nickname (gw), plus shows the aliases are usable in resolve_ref. This adds real semantic meaning beyond the bare schema field names. Could be improved with format expectations (e.g., valid alias characters), but the example handles the core semantics well.

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 purpose: 'Add a short nickname for an entity' with the constraint 'Globally unique.' The verb 'Add' plus resource 'alias for an entity' is specific. It doesn't explicitly distinguish from its sibling remove_alias, but the action itself is clear enough. The example reinforces the purpose with a concrete usage.

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 implies usage context: creating short nicknames for entities to enable shorter references. The example showing add_alias followed by resolve_ref demonstrates the intended workflow. However, it doesn't explicitly state when NOT to use this tool or mention alternatives (e.g., when to use remove_alias for cleanup), and doesn't cover constraints beyond global uniqueness (charset, length limits, what happens on duplicate).

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