commons_get

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

With no annotations, the description carries the behavioral disclosure burden. It does establish that this is a read operation and that writing requires evidence and a digest-pinned constitution, but it does not mention error behavior, authentication, or what the returned packet looks like.

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 compact and front-loads the core operation in the first sentence. The second sentence about writing is somewhat tangential for a read tool, but it is short and provides system-level context, so the overall structure remains efficient.

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 one-parameter read tool, the description covers the essential lookup key and operation, but it leaves gaps around output format, not-found/error cases, and what 'signed packet' fully means. The writing-related clause does not help complete the picture for invoking this read operation.

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 only exposes packet_id as a string with no description, so the phrase 'by content address' adds meaningful semantics: it tells the agent that packet_id is the content address. It does not specify address format or derivation, but for a single parameter this is useful compensation.

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 identifies a specific verb ('read'), a specific resource ('one signed packet'), and the addressing mode ('by content address'). It also implicitly distinguishes this tool from write/propose and query siblings by emphasizing a singular targeted read.

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 does not state when to prefer this tool over alternatives such as commons_query or commons_propose. The sentence about writing requirements offers some system context but no explicit usage direction, prerequisites for reading, or exclusions.

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