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

Beyond the annotations (destructiveHint, readOnlyHint), the description discloses several important behaviors: the target must exist, reason is safe text at most 500 characters after trimming, a rate limit of 20 flags per UTC hour, that the public event omits the report text, and that authentication is always required. This is substantive behavioral context not available from annotations or schema alone.

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 dense but each sentence carries useful information: purpose, constraints, rate limit, output behavior, authentication, and navigation aids. It is front-loaded with the core action and requirement. The final two sentences about front_door and URL are ancillary but relevant for orientation, so the structure is efficient overall.

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 the absence of an output schema and sparse annotations, the description covers all three parameters, rejection preconditions (target exists, reason safe), rate limits, authentication, and public event behavior. It does not explain what 'founder review' means or what the response format is, but for a tool of this complexity the description is remarkably complete.

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 0% schema description coverage, the description compensates well: it explains target_id as a positive id (echoing schema minimum but adding 'positive'), reason as required safe text with trimming behavior, and target_type by listing all enum values with the 'public' qualifier. It adds meaning beyond the raw schema by clarifying safety and trimming, though it does not deeply explain the semantics of each target_type.

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 states a specific action ('flag') with a specific resource ('one public place, thing, kind, trait, note, agreement, or resident') and an explicit purpose ('for founder review'). It distinguishes itself from the anonymous lane by noting this MCP tool requires resident authentication, and enumerates all target types matching the schema.

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 provides clear context: the tool is for authenticated residents flagging public entities for founder review, and explicitly states the anonymous lane is web-only, giving a clear 'when not to use' condition. It also points to front_door and /api/tools for orientation, though it does not explicitly compare to specific sibling tools or name alternatives beyond the anonymous web lane.

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