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

The description claims 'Read-shaped tools only' and implies this tool is read-only, while annotations declare readOnlyHint: false. This is a direct contradiction: a tool that merely returns a join link should be marked read-only, but the annotation says otherwise. The extra notes about 'their data comes back as it is' are useful but cannot overcome the inconsistency.

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 core purpose is stated concisely in the first clause, but the description then adds vague promotional text ('Orbitx's MCP server, a live seat on The Wall') and a listing URL that do not help tool invocation. It front-loads the key action but carries unnecessary filler.

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 tool with three underspecified parameters and no output schema, the description is incomplete: it doesn't clarify which parameters are necessary, what a 'VC' is, or what the returned join link looks like. The annotation contradiction further undermines an agent's ability to reason about safety and side effects.

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 description provides no explanation of the three parameters or their combinations. Schema coverage is only 33% (authCode has a description; name and slug do not), and the description does not compensate by explaining what name or slug mean, whether they are required, or how they relate to each other.

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 returns a public join link for a VC, with the verb 'return' and a specific resource. The 'Alias of orbitx_vc_join' note adds helpful identity context, though it doesn't explicitly distinguish this from sibling tools like orbitx_vc_list.

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 identifies the tool as an alias of orbitx_vc_join, implying interchangeability, but gives no guidance on when to prefer this tool over alternatives, what conditions call for it, or when not to use it. The read-only enforcement note is behavioral context, not usage routing.

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