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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: records only exist after an authorized workflow is verified, and no repository is inferred from a recipe or name. It still doesn't disclose pagination behavior or result ordering.

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?

Three sentences, front-loaded with purpose, then the semantics, then the exclusions. Every sentence carries content, though the final negative list is slightly sprawling.

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 read-only list tool with no output schema, the description should at least hint at what a 'connection' record contains and how cursoring works. The verification caveat is valuable, but the pagination and return-shape gaps leave an agent under-informed about repeated calls.

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% across 4 parameters. The description clarifies that project/environment are the required scope, but says nothing about limit (max 100, default 25) or the opaque cursor, leaving pagination semantics entirely unexplained in both schema and prose.

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 ('List verified GitHub repository/workflow connections') plus the scope ('explicit project/environment'), so an agent knows exactly what is returned. It also pre-empts the natural confusion with App installation / connection creation tools by stating those are out of scope.

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 negative clauses ('Does not install the App, create a connection, execute a simulation or change repository access') effectively tell the agent when this tool is NOT the right one. It stops short of naming the sibling tool to use instead for those actions, so it is clear context without explicit alternatives.

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