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

Annotations only declare readOnlyHint=false and destructiveHint=false, leaving behavior underexplained. The description adds crucial behavioral nuances: the 'act' scope requirement, the guarantee of no spend/posting, the instruction to 'Keep run_key stable' (implying idempotency or state consistency), and clarification that 'Source URLs are evidence, not reply targets.' While it doesn't cover all side effects or return behavior, it adds meaningful disclosure beyond the bare annotations.

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 five short, dense sentences that front-load the core purpose ('File a growth idea or original X draft') before diving into constraints. Every sentence adds value—scope, spend/posting, run_key stability, draft requirements, source_url interpretation, and workflow tip. There is no filler or redundancy; the structure is efficient and easy 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?

For a tool with 11 parameters, a nested object (source_idea), and no output schema, this description is insufficient. It covers a few key constraints but leaves many parameters undefined (why, text, title, claim_ids, etc.) and does not describe what the tool returns or how to handle errors. The agent is left guessing on significant parts of the invocation, which is a substantial gap given the tool's complexity.

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 description coverage is 0%, so the description must compensate, and it does for a few critical parameters: it explains that new drafts need action_kind social_post and either idea_id or source_idea, and clarifies source_url usage ('evidence, not reply targets') and run_key stability. However, of the 11 parameters, many remain unexplained (why, text, title, channel, claim_ids, etc.), and the meaning of operation is only implicitly tied to 'idea or draft.' This partial coverage earns a 3.

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 opens with 'File a growth idea or original X draft,' a specific verb-resource pairing that clearly identifies what the tool does. It distinguishes itself from siblings like record_claim or record_insight by focusing on growth ideas and X drafts, and the resource is internally precise (idea vs. draft). Even though no sibling is named, the purpose is unambiguous and the scope is well defined.

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 solid usage context: it requires 'act' scope, explicitly states 'no spend or posting' (a when-not), and prescribes conditions for new drafts ('New drafts need action_kind social_post and one idea_id or source_idea'). It also advises 'Read get_move; use existing move verbs for completion,' which guides workflow but does not explicitly name alternative tools. This is clear context without formal when/alternatives differentiation, so a 4 is appropriate.

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