Describe TOCA Capability

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

Annotations already establish a safe read profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description is fully consistent with these. It adds genuine value by revealing that input may be an alias subject to resolution and that the return payload carries typed, policy, and lifecycle contract fields — behavior not inferable from the annotations.

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?

A single dense sentence of 15 words with zero wasted words. Every phrase carries meaning: 'resolve aliases' (behavior), 'canonical' (output quality), 'typed, policy and lifecycle' (contract shape), 'one' (cardinality). The density is justified by the semantic load, not padding.

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 lookup tool with one string parameter, no output schema, and strong annotations, the description is complete. It conveys the resolution behavior, the canonical nature of the result, and the contract fields returned. Nothing material (auth, error handling, rate limits) is expected at this complexity level for an idempotent read.

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 for the single capabilityId parameter. It partially does: 'one capability' clarifies singular cardinality and 'resolve aliases' hints that the string may be a valid alias rather than a canonical ID. However, it never explicitly confirms that capabilityId accepts canonical IDs, aliases, or both, leaving the input contract somewhat ambiguous.

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 uses a specific verb+resource construction: 'Resolve aliases and return the canonical typed, policy and lifecycle contract for one capability.' It precisely scopes to a single capability and differentiates from the sibling toca.capabilities.search by emphasizing alias resolution to a canonical form — a distinct read semantic.

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?

Usage is implied through active phrasing: 'Resolve aliases' signals its role as the normalization/lookup endpoint for a single capability, implicitly contrasting with search (for discovery) and the workflow/approval siblings. However, there is no explicit when-to-use, when-not-to-use, alternative naming, or mention of failure behavior for unknown aliases.

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