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

Annotations only give the generic write profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds real context beyond that: no charge, agent-key auth (X-NW-User-Key), the downstream visibility of the record in GET /forge/vaults/{id}/mirrors/me as source self_report, and the superseded-signal refusal. It stops short of addressing duplicate/idempotency behavior, which is the one trait annotations flag.

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?

Dense but front-loaded: purpose first, then write/no-charge, then required params, then visibility and refusal. Every sentence carries information, though the parameter list reads as one long run-on that could be tightened.

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 7-param write with no output schema, it covers auth, constraints, side-effect visibility, and the main failure mode. An agent has enough to call it correctly; only edge behavior like repeat submissions is unaddressed.

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?

With only 43% schema description coverage, the description carries the load and does so well: account_address is constrained to one of your active mirrors, filled_at must be ISO-8601 and not in the future, side must match the signal, and venue_order_id is optional. These are semantic constraints the schema does not express.

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 (report) and resource (the fill from a forge_signal_plan execution) plus the underlying endpoint POST /forge/signals/{signal_id}/fills. It clearly distinguishes itself from the sibling forge_signal_plan, which creates the plan rather than recording the resulting fill.

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?

Explicitly ties use to having executed a forge_signal_plan on your own account, and names the sibling that produces the prerequisite. It also gives a refusal condition (a superseded signal is refused), but does not spell out when-not-to-use cases such as duplicate reporting.

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