Connect cluster info

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

No annotations are provided, so the description carries the full burden. It indicates what information will be returned but does not explicitly state that this is a read-only operation, that no authentication or config is required, or whether the worker version and cluster id are safe to access without side effects. The absence of an output schema also leaves the return format unexposed.

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 a single, efficient sentence that names exactly what the tool surfaces. Every word is relevant, and there is no filler or redundant restating of the title.

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 parameterless metadata retrieval tool, the description is essentially complete: it lists the three values an agent will receive. It would be slightly improved by explicitly stating the operation type, such as 'retrieves' or 'returns,' but given the trivial interface, nothing else is truly needed beyond the field list.

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?

There are zero parameters, so the schema already provides 100% coverage. The description is not required to explain any parameter behavior. A baseline of 4 is appropriate because the description adds no unnecessary parameter detail and the tool needs none.

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 names the specific resource (Kafka Connect cluster) and the concrete fields returned: worker version, commit, and Kafka cluster id. It is clear what information is being requested, though it lacks an explicit verb and does not directly differentiate itself from the sibling tools, which are all connector-focused.

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 context of this tool is reasonably implied by its name and field list: it is used when cluster-level metadata is needed. However, there is no explicit guidance on when to choose it over alternatives, nor any exclusions such as 'use this when you need connector details rather than cluster info.'

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