threads_connect

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

Annotations only declare this is not read-only and not destructive, which is thin for a session/credential flow, and the description goes well beyond that: the token is entered on a local page and never passed through chat, cancel leaves saved accounts connected, and pending means the user has not yet finished. It stops short of stating failure/timeout behavior (e.g., what an expired URL returns) or any local-server prerequisite.

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?

Compact and mostly front-loaded, with the safety point (token never sent to chat) placed first where it matters. The action-by-action sentences read as a fragmented run-on with no visual separation between actions, so a scanning agent has to parse lines rather than bullets.

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?

An output schema exists, so return shape need not be described, yet the description still explains the meaningful states (connected includes the public profile, pending means waiting). What remains uncovered is the precondition for the whole flow — that a local page/server must be reachable — which an agent needs to interpret a failure.

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 0% and the enum values start/restart/cancel are bare in the schema, but the description defines each one: start opens a form or returns the current URL or result, restart opens a new form for another account or replacement token, cancel closes the form while preserving connected accounts. That is full compensation for the undocumented parameter.

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 first sentence states a specific verb and resource (connect a Threads account) and adds the distinguishing mechanism (a local page, token never sent to chat). That immediately separates it from the entire sibling set of publish/list/insight tools, none of which touch account connection.

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 spelled out per action: show the URL to the user, call start again to poll, connected vs pending semantics, restart for another account or a replacement token, cancel to close the form. What is missing is any tie-in to the account-facing siblings such as threads_list_accounts, which an agent might otherwise reach for after connecting.

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