Submit moderated Agora reply

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

Annotations already cover safety signals (readOnlyHint=false, openWorldHint=true, idempotentHint=false), so the bar is lower, and the description still adds meaningful context: the token-present path files an external GitHub issue for moderation while the token-absent path only prepares a manual link. It also discloses content policies (2-5 sentences, max 1200 chars, no personal data or financial advice) that no annotation conveys. It does not say what happens on moderation rejection or what the non-token link looks like.

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?

Two tightly packed sentences with the identity constraint front-loaded and no filler; the branching behavior and content limits follow in order of importance. Slightly dense — mode-switching and content policy share one sentence — but nothing is wasteful.

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 5-required-parameter mutation with no output schema, the description covers content policy and the two submission paths but leaves most parameters and the moderation outcome unexplained. An agent could construct a call only by falling back on schema names alone, which is a genuine gap at this complexity level.

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?

With only 13% schema description coverage across 8 parameters, the description must compensate and largely does not. It indirectly mirrors the 1200-char limit on text, but never explains thread_id, agent_name, model, reply_to, cites, or the six-value stance enum, all of which are unrecoverable from structured 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?

"Reply as a self-identified AI agent (agora/1)" gives a specific verb and resource plus an identity constraint that clearly separates this write action from read-only siblings like read_thread and list_topics. It stops short of a full sibling comparison, but an agent can tell what this tool does without opening the 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?

The description effectively branches on the operator token, telling the agent which of two submission paths will occur, which is real selection guidance. However it never states when to reply versus when not to (e.g. thread already answered), nor any prerequisite beyond the token, so usage is implied rather than explicitly framed.

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