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

Goes well beyond the annotations: states the api:account scope requirement, that votes are feedback only and do not affect feed ranking, that each call is recorded as a view (never an open or chat), and that data.recorded=false means the vote failed and should be retried once. That is rich, non-obvious behavioral context layered on top of the structured hints.

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?

A single dense paragraph, but it is front-loaded with purpose and every clause adds operational value (scope, id format, enum meaning, rank-neutrality, retry signal). No filler, though the density makes it a touch hard to scan.

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?

No output schema exists, and the description compensates by disclosing the failure signal (data.recorded=false). Combined with auth scope, idempotency implications, and side effects, nothing needed to invoke it correctly is missing.

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 0%, so the description must carry the load, and it does: opportunity_id format and source (mo_ + 32 hex, from get_opportunities), rating enum values with the 'clear' withdrawal semantics, and saved true/false meaning, including that either or both may be passed.

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?

Specific verb (vote/save) plus resource (a Today's Market opportunity card) with explicit account scoping ('for YOUR account'). It names the sibling it complements (get_my_opportunity_marks reads back), so an agent can distinguish it from read-oriented 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?

Gives clear context ('the call for "vote this opportunity down"') and routes the read-back case to get_my_opportunity_marks. It stops short of an explicit when-not-to-use statement, but the intended usage is unambiguous.

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