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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) by explaining exactly what is and isn't changed: "it hides no lot, changes no alert and teaches the search nothing." It discloses auth requirements, the 25-per-search cap, dedup behavior via skipped=already_flagged, and enumerates the full skipped vocabulary so the agent can interpret partial failure.

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?

Purpose and the human-confirmation caveat are front-loaded, then progressively finer detail (params, non-effects, return shape, limits). It is a single dense paragraph that is longer than the minimum, with a few sentences that duplicate the schema, but almost every sentence carries operational weight.

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?

There is no output schema, and the description compensates fully by documenting the return shape: results with { lotId, proposed, flagId } or { lotId, proposed: false, skipped } plus the pending/limit object. Combined with the auth, limit and side-effect disclosures, an agent has everything needed to call this correctly and interpret the response.

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 75%, and the description adds real value by stating provenance ("lotId comes from screenLots with that profileId") and that evidence is a short free-text observation, not a verdict. Some content (the reasonCode list, the 1–25 bound, preview behavior) merely restates the schema, so it adds lineage rather than fully new semantics.

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: "Suggest that results of one saved search are not a fit", and immediately clarifies the human-in-the-loop nature ("for the user to confirm or reject on the result row"). It explicitly disambiguates from sister tools (submitBuckyFeedback) and names screenLots as the source of lotId, so an agent can distinguish it from siblings without opening any 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?

Strong operational guidance: signed-in only, write scope, preview=true proposes nothing, "never propose it again" for declined lots, and at the 25-per-search limit "wait for the user to answer". It names an explicit alternative to avoid (submitBuckyFeedback) and a prerequisite source (screenLots). What it lacks is an explicit trigger statement for when a lot should be judged "not a fit" beyond the reason codes.

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