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

Annotations already declare this is a non-read-only, non-destructive call against a closed service, so mutation intent is covered. The description adds a real consequence clause — reports "earn extra checks and protect other agents" — which is behavior beyond the annotations. It does not say what is stored, whether reports are public or reviewed, or whether the submitted URL is shared onward.

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 short sentences, front-loaded with the action, then the kind-selection rules, then the incentive. No filler, no repetition of schema fields.

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?

With four parameters, no output schema, and thin annotations, the definition covers purpose, kind semantics, and motivation adequately. The remaining hole is what happens after submission — whether the call returns a confirmation, an ID, or contributes to a quota — which matters somewhat given the daily-limit mechanic mentioned only in the schema.

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 only 50%: url and kind have no schema descriptions at all. The description compensates for the most important gap by defining the semantics of all three kind values, which the bare enum does not convey. It says nothing extra about url, and note/api_key are already documented in the schema.

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?

"Tell Flockward about a page you visited" states a specific verb and resource, and the three sentence-level clauses define what kind of page report is being made. It is clearly a submission tool rather than a lookup tool like check_url or fetch_safely, though it never explicitly contrasts itself with any sibling such as send_feedback.

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 concrete routing rules for each enum value: "suspicious" for hidden text, agent-directed instructions, or secret/payment requests; "visit" for a normal page; "false_positive" for a page wrongly flagged. That is unusually explicit usage guidance. It stops short of when NOT to file a report (e.g., duplicates, already-known pages) or how this differs from send_feedback.

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