connections_geocheck_by_node

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

With no annotations, the description carries the full behavioral burden, and it does disclose the key trait: this is an async operation that returns a job ID rather than a result, plus the up-to-a-minute latency. However, it omits that this is a POST mutation, that the confirm parameter gates actual execution (preview otherwise), and any auth requirements.

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 operative content is two tight sentences, but the raw endpoint line 'POST /api/connections/geocheck/{nodeUuid}' and the 'Tags: Connections Controller' trailer are generated filler that pushes the real purpose behind noise instead of front-loading it.

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 async, no-output-schema tool, the description covers the critical gotcha (returns a job ID, must poll a sibling, up to a minute delay). It lacks detail on what a geocheck actually does and the confirm-preview behavior, but the information an agent needs to call it correctly is essentially present.

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 67%, so most parameters are already documented in the schema (nodeUuid, body.ip, body.interface, and the confirm flag with a detailed Russian-language explanation). The description adds only the implied role of nodeUuid via the URL template and no meaning for the body fields, so it neither compensates for nor extends the schema.

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 ('Queues a geocheck on the node') and explicitly frames the tool as the queueing half of an async pair, naming the sibling result tool 'Get Geocheck for Node by Job ID'. An agent can tell it apart from connections_geocheck_by_node_result without opening either 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?

Explicitly routes the agent to the follow-up tool for the result and gives a timing expectation ('the node may take up to a minute to answer'), which is exactly the when-to-use context for an async job tool. It stops short of stating when-not to use it or any prerequisites.

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