reputation_give_feedback

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

With no annotations, the description carries the full burden. It usefully discloses internal WAD normalization and the unlocked-wallet requirement, but says nothing about on-chain cost, irreversibility, or that submitted feedback can later be revoked via a sibling tool — gaps that matter for a 10-param mutation.

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 and normalization note are front-loaded and efficient. The trailing tip about earning_opportunities is promotional and does not help the agent invoke this tool, so it fails to earn its place.

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?

Given 10 optional/required params, no annotations, and no output schema, the description tells the agent what the tool does, how the numeric value is interpreted, and what wallet state is needed. The remaining gaps are behavioral depth rather than missing information required to call it.

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 coverage is 100%, so baseline would be 3. The description adds real value by explaining that value is normalized to 18 decimals (WAD) internally for aggregation, which clarifies the value/valueDecimals relationship beyond the per-field schema text.

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?

States a specific verb and resource ('Submit feedback for an agent using the ERC-8004 reputation registry'), which is unambiguous. It does not explicitly differentiate itself from close siblings such as reputation_append_response or reputation_revoke_feedback, but the verb makes the function clear.

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 prerequisite 'Requires an unlocked wallet' is stated, which is useful before attempting a write. However, there is no guidance on when to prefer this over reputation_append_response or reputation_revoke_feedback, and the closing tip about earning_opportunities is unrelated to usage of this tool.

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