publish_sensemaking_topic

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

With no annotations, the description carries the transparency burden. It discloses the outcome (live /t/[slug] page built from project sessions), the precondition (editor access), and an important behavioral caveat (listing on /explore is separate). It does not describe edge cases like idempotency or error behavior, but for a publish action the key behaviors are covered.

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?

Three sentences, each earning its place: the purpose, the publication trigger, and a key permission/caveat. No filler or repetition of schema details.

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 publish action with 10 parameters, the description covers the main behavior, preconditions, and a caveat. The schema documents parameter details, so the description focuses on process. It lacks mention of what happens if the slug already exists or whether unpublish is the inverse, but these are minor gaps.

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 100%, so baseline is 3. The description adds meaning beyond the schema by explaining that slug can be provided in this call or already saved on the project, and it links enabled:true as the publication trigger. This clarifies the relationship between two key parameters.

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 specific verb+resource+outcome: 'Author and publish a Harmonica project as a public sensemaking topic.' It clearly distinguishes this from sibling tools by specifying the two artifacts created (/explore hub entry and /t/[slug] opinion-landscape page).

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 clear usage context: to publish, pass enabled:true with a slug; requires editor access. It also notes that /explore listing is a separate admin-curated step, managing expectations. It does not explicitly name alternative tools for similar actions, but the unique publish action makes the context clear.

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