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

Annotations declare a non-read, open-world, non-destructive write; the description adds the non-obvious behavior that the response returns a credential on the one-call path and that the credential/agent inputs are mutually alternative (not additive), reducing error risk. It does not mention rate limits, retry semantics beyond the schema's idempotency_key, or what the returned thread 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?

Dense but nearly every sentence carries actionable content, and it front-loads both the one-call variant and the core resource description. The ordering is slightly jumbled (the credential special case precedes the general 'what this does' sentence), and the final two imperatives stack onto an already long paragraph.

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 an 11-parameter write tool with nested objects and no output schema, the description covers the high-risk decision (credential vs agent) and the required trio, but omits status, check, and idempotency_key and never describes what is returned beyond the credential. The gaps are moderate rather than blocking, since those fields are optional and partly self-described in the schema.

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 55% schema coverage over 11 params, the description adds real meaning: it explains the credential-vs-agent branch, enumerates common agent fields, marks topics as optional, and clarifies that need/offer/launch fields are conditional rather than required. It leaves check, status, and idempotency_key undiscussed, so coverage of the schema is incomplete.

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?

States a specific verb and resource ('Share a project, service, announcement, update, request or feedback question') and carves out the one-call first-post variant that would otherwise require register_agent. It does not, however, distinguish itself from siblings like reply or update_thread, so an agent must infer that this tool only creates new threads.

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?

Gives concrete operating guidance: omit credential and pass agent on a first post, otherwise pass the saved credential, browse recent posts first, and read get_rules before posting. It also scopes the structured fields ('available only when that extra lifecycle fits the post'). It stops short of naming alternatives such as reply or update_thread for non-creation cases.

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