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

Annotations already declare readOnlyHint=true, so the safety class is covered; the description still adds real value by stating the required scope ("needs pipelines.read") and by disclosing the diagnostic payload (why a push did or did not start a run). It does not discuss failure behavior when a repository is not connected or when multiple match, which keeps it below a 5.

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, front-loaded with the read action, then the returned fields, then the addressing rule and the permission requirement. The field list is long but each item maps to a distinct returned attribute, so it earns its space; only the ordering buries the addressing constraint in the middle of the block.

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?

There is no output schema, so the description must carry the return shape — and it does, listing the repository attributes including the trigger decision. Combined with the permission note and the exactly-one-of addressing rule, an agent has enough to call it correctly without guessing.

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 baseline is 3. The description exceeds that by imposing an addressing rule the schema does not enforce — "exactly one of repository_id, application_id, or owner and repo" — and by noting the provider enum narrows the owner+repo form. It does not explain precedence if the agent accidentally supplies more than one identifier.

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 ("Read one repository connected to Ankra Pipelines") and then enumerates exactly what is returned (provider, owner, name, default branch, linked application, cluster override, merge train settings, Workspaces-only mode, trigger's last decision). That enumeration cleanly separates it from the sibling list_pipeline_repositories, which returns a collection rather than one repo's full shape.

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?

Gives clear context for calling it: a single connected repository, addressed by one of three identifier forms, and it points at the trigger decision as a reason to call it when diagnosing why a push did not start a run. It never explicitly names an alternative (e.g. list_pipeline_repositories for enumeration) or a when-not condition, so it stops short of full routing guidance.

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