togoid_getRelation

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

The annotations already indicate the tool is read-only (readOnlyHint: true) and may return varying data (openWorldHint: true), covering safety and variability. The description adds crucial behavioral detail: it returns a JSON string of an array of relationship objects with specific fields (forward, reverse, description), and clarifies that an empty array means no direct route exists. It also notes that it is a single-hop pairwise check. This adds context beyond the annotations without contradicting them.

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 well-structured and appropriately sized. It opens with a clear purpose statement, then immediately gives usage guidance and a contrast with a sibling tool. The return format is described concisely in a separate paragraph, using bullet-like structure. Every sentence adds value, and there is no fluff or repetition.

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?

The tool is relatively simple (2 params, no nested objects), and the schema covers both parameters fully. The output schema is present, so return values don't need to be overly detailed, but the description still gives a clear summary of the return structure. The description also clearly explains the tool's role in the broader workflow (verify before convertId), and differentiates it from other relation-related tools. It is complete for an agent to select and invoke this tool correctly.

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 already provides examples for both parameters ('uniprot', 'ncbigene' etc.), so coverage is high. The description adds semantic meaning by framing them as 'source' and 'target' for a route check, and explicitly mentions that they are passed separately (unlike convertId). It also tells the user that these are database keys, but the schema examples already did that. The added value is the clarification of how to pass them, which is useful.

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 that the tool checks if a specific ID conversion route exists and retrieves its details. It specifies the action ('Check', 'get details'), the resource ('ID conversion route'), and differentiates it from sibling tools like togoid_convertId (which actually converts) and togoid_getAllRelation (which lists all relations).

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 explicitly states when to use this tool: 'Use this to verify that a particular source→target conversion is available before calling convertId.' It also provides a clear contrast with convertId, which takes a comma-joined route, and explains that this tool requires separate 'source' and 'target' arguments. This gives clear usage guidelines and differentiates from the closest sibling.

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