list_projects

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds non-obvious behavior beyond that: it takes no input and it never lists deleted projects, which prevents a wrong inference that the list is exhaustive of all historical projects. It stops short of saying anything about ordering or scale.

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?

Front-loaded with the purpose, then usage, then an edge case, with no filler marketing language. Slightly longer than strictly necessary, but each sentence carries distinct information.

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 zero-argument, read-only list tool with an output schema present, the description covers purpose, usage precedence over other tools, and the deleted-project exclusion. Nothing an agent needs to call it correctly is missing.

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 baseline is 4. The description confirms the zero-argument nature ("takes no input"), which is a small but real reinforcement rather than a restatement of a rich 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 ("List every project the operator has registered with ccc-mcp") and names the payload returned (id and root folder). It explicitly contrasts with the sibling bootstrap_project, so an agent can distinguish the two 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?

Gives an explicit ordering instruction ("Call it first to learn a valid project_id for every other tool") and names the alternative for the deeper case (bootstrap_project to inspect one project). Both when-to-use and the routing alternative are spelled out.

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