Import a channel’s past posts

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses the dry-run default and confirmation requirement, the cost quoting, the resumability, and the crucial caveat that imported posts are weaker evidence, labelled 'backfilled', with hooks only recovered under specific conditions. It also warns 'Never guess a hook from a caption.' This is rich, honest behavioral disclosure that goes well beyond the structured 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 dense but every sentence earns its place. It front-loads the core purpose, then systematically covers supported channels, exclusions with reasons, the dry-run/confirm/resume workflow, and the evidence caveat. No filler or repetition; the length is justified by the tool's complexity. The structure uses punctuation effectively to keep it readable.

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 complex tool with 5 parameters, no output schema, and nuanced behavior, the description provides everything an agent needs to call it correctly: what it does, which channels work, why others don't, the default dry-run behavior, how to confirm, how to resume with a cursor, and what happens to imported posts regarding evidence. Even the return value is hinted at ('tells you how many posts it found and what reading them will cost'). Nothing critical 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 description coverage is 100%, so the schema already documents all five parameters. However, the description adds essential contextual meaning: it explains that limit caps the page size (default 50, max 200), that cursor is for resuming, and that confirm:true is the flag to actually import while omitting it triggers a dry run. It also clarifies accountRef for multiple accounts. This is meaningful added value beyond the schema fields.

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 a clear verb-resource pair: 'Import this brand's PAST posts from a channel into the performance record.' It names the exact purpose (feeding 'which hook works' with history) and lists all supported channels, which distinguishes it from posting, insight, and metrics tools in the sibling set. There is no ambiguity about what this tool accomplishes.

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 gives explicit workflow guidance: it runs as a DRY RUN by default, requires confirm:true to import, and uses the returned cursor to resume. It also states the intended scenario ('draw on history rather than only on what was published since Hermoso started recording'), and even explains why certain channels are excluded, which prevents inappropriate attempts. This is far above the minimum.

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