network_reputation

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

With no annotations, the description carries the full burden and exceeds it. It discloses return semantics (magnitude range, confidence as non-probability weight), scalar meaning at 0.0, vantage-specific computation, anonymity of reports, impossibility of discovering DIDs, and signing requirements. This is exceptional behavioral transparency.

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 long but every paragraph earns its place. It uses bolded key terms, a clear opening line, 'Advisory' marker, and logical flow from purpose to interpretation to caveats. No filler or redundancy.

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?

Despite its complexity, the description is complete: return values, interpretation pitfalls, privacy guarantees, prerequisites, and edge cases are all covered. It stands alone even without an output schema, and the explicit distinction from sibling tools provides full contextual grounding.

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?

Although the schema only lists counterparty_did, the description enriches it substantially: it explains the parameter is a DID, that results are computed relative to your own DID, and that an unknown DID yields confidence 0.0. It also explicitly addresses the 'unknown agent' edge case, fully compensating for the schema's lack of detail.

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 a specific verb and resource: 'Ask the network what it can tell you about another agent.' It clearly distinguishes itself from siblings by naming record_interaction as its counterpart ('The other half of record_interaction') and referencing recall_counterparty and check_media_signals as distinct inputs.

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 guidance is explicit: it contrasts with record_interaction ('That tool tells the network what happened; this one asks the network what others have told it'), and the 'Advisory' section explicitly frames it as one input among others, naming alternatives. It also specifies prerequisites (SYNPAREIA_NETWORK_URL, published identity) and a critical reading order ('Check confidence first').

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