retrieve_connections

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

With no annotations provided, the description carries the full burden and it excels: it explains the queued cloud-browser workflow, immediate pending response with status fields, long-poll mechanism, and distinct pending reasons like 'outsideWorkingHours'. It also warns against retrying to avoid duplicate queued work, which is valuable behavioral disclosure.

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 longer than typical but every sentence contributes necessary information about the async workflow and special cases. It is front-loaded with the core purpose, then explains the process in a structured, readable way. Slight redundancy (e.g., mentioning the operationName twice) keeps it from a 5.

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?

This is a complex asynchronous tool with no output schema, and the description covers all necessary context: immediate return shape, how to retrieve the final result via get_workflow_result, behavior for queued vs outsideWorkingHours, and instructions not to retry. It is complete enough for an agent to correctly invoke and follow up.

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 the schema already documents all parameters thoroughly. The description adds minimal parameter-specific detail beyond what the schema provides (e.g., mentioning 'when filter is not provided' for the since parameter), which is already in the schema. Thus the baseline of 3 is appropriate.

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 clearly states the tool retrieves connections and names the underlying action (st.retrieveConnections). It is specific about the resource (connections) but does not explicitly contrast itself with sibling tools like retrieve_pending_requests or search_people, so it misses the differentiation that would merit a 5.

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 clear context on how to handle the asynchronous workflow (use get_workflow_result, don't retry while running), but it does not say when to choose this tool over alternatives like search_people for broader people search. The when-to-use is implied by the name and description, not explicitly stated.

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