What to post next

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

Annotations only declare readOnlyHint and openWorldHint, so the description carries the interesting part: behavior branches on whether an AI model is configured, yielding either structured ideas with format/hook/angle/evidence/confidence or raw data to reason from. That two-mode disclosure is genuinely useful and not present in structured fields. It stops short of noting pagination, volume limits, or what happens with sparse account history.

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?

Roughly one dense sentence, front-loaded with the purpose before the AI/non-AI branch. Nearly every clause earns its place, though the AI-vs-raw-data clause runs long and could be split for scanability.

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 no output schema, the description does the right work by sketching the return shape (format, hook, angle, evidence, confidence) and flagging the degraded non-AI mode. The remaining gap is the undocumented 'template' parameter and the size of the performance lookback, which an agent would want before calling.

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 40%, so the description needs to compensate and largely does not. It explains 'focus' as an optional topic and hints that performance is drawn from recent posts, but leaves 'count', 'posts' (the lookback window size) and especially 'template' entirely undefined in both schema and description.

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 names a specific output (next post ideas), the grounding signal (this account's recent performance, formats and topics scored against the account's median), and an optional narrowing (a topic). This is clearly separable from siblings like analyze_post or find_outliers, which diagnose past performance rather than propose future posts.

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?

Usage is implied by 'next post ideas' and by the optional focus parameter, so an agent can infer when to reach for it. However, it never states when not to use it or names a sibling alternative (e.g. hashtag_research, generate_caption) for adjacent needs, leaving routing to inference.

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