Get Joint

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds useful behavioral context beyond that by explaining the dual-network behavior, the mainnet default, and the need to confirm network choice. No contradiction exists between the description and 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?

Three sentences, all of which add value. The core action is front-loaded as 'Raw hub read', followed by the network requirement and user-confirmation guidance. There is no filler or repetition of schema details.

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 description covers the main non-obvious contextual issue, network selection, and is backed by annotations that establish safety and idempotency. It does not describe the joint response shape or explicitly separate this raw read from sibling analysis tools, but for a simple hub read with no output schema the provided context is mostly sufficient.

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%, but the description compensates by explaining that 'unit' is a unit hash and specifying how to pass the network parameter, including the mainnet/testnet values and the default. It could go further by defining what a 'joint' is, but the essential parameter semantics are addressed.

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 opens with 'Raw hub read' and states it 'Fetches the joint for one unit hash from the selected hub', which is a specific verb, resource, and input. It conveys a low-level read operation, but it does not explicitly contrast this tool with sibling tools like obyte_analyze_unit or obyte_get_history.

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 gives clear usage context: the server serves both Obyte networks, the network parameter selects which one, and the default is mainnet. It also instructs the agent to confirm the user's intended network when not explicit, which is actionable guidance, though it lacks explicit when-to-use vs alternatives statements.

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