Get Runner

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered; the description adds value beyond that by disclosing a security-relevant behavior (runner authentication tokens are never returned) and an access constraint tied to project_id. It stops short of stating what happens when the runner is not available to the project (e.g., error vs. empty result).

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?

Two sentences with zero waste; the returned-field list comes first and the access/token caveats follow. Every clause carries information an agent needs.

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?

With no output schema, the description compensates by listing the returned attributes and explicitly excluding tokens, and it covers the one non-obvious parameter constraint. Only minor gaps remain (error behavior when the runner is inaccessible, effect of omitting project_id).

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 description coverage is 0%, so the description must carry parameter meaning: it clarifies that project_id acts as a visibility/authorization scope ("must be available to project_id") and that runner_id selects a single runner. It still adds nothing about runner_id's numeric-string format or the consequences of omitting project_id.

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?

Names a specific verb and resource ("Get one runner") and enumerates the fields returned (tag_list, run_untagged, locked, access_level, status, version), so an agent knows exactly what it will receive. It does not need to differentiate from a sibling runner getter, but it also doesn't position itself against anything else.

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?

Provides one concrete precondition – "The runner must be available to project_id" – which tells the agent the context needed for the optional scope parameter. There is no explicit when-to-use vs. when-not-to-use guidance or guidance on omitting project_id versus supplying it.

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