Register a repository

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

Annotations only give readOnlyHint=false and openWorldHint=false; the description goes well beyond that, disclosing that the path is validated as a git repo at registration time, that nothing is cloned or fetched, that mirror-backed projects surface in list_repos before first read, and that re-registration preserves the existing freshness policy. These are exactly the behavioral traits an agent needs before calling.

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 core action is front-loaded, followed by conditional behavior, side-effect exclusions, and re-registration semantics in four tight sentences. No filler and no repetition of schema or annotation content.

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-required-param, two-parameter registration tool with no output schema, the description covers validation timing, side effects (no clone/fetch), visibility effects, idempotence, and alternative tools. An agent has everything needed to invoke it correctly and to route elsewhere when cloning is actually wanted.

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, but the description adds real meaning beyond the schema: it explains what selecting local_path changes (reads use that clone rather than a mirror) and that the path is validated here, while the schema only says 'Path to an existing clone'. The project parameter's default behavior is left to the schema, which already covers it.

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?

Opens with a specific verb+resource ('Register a project with this server') and immediately differentiates the two registration modes: local_path clone-backed vs. mirror-backed. The distinction from siblings (sync_repo, list_repos) is made explicit in the body, so an agent can place this tool without opening any 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?

States precisely when to supply local_path (read from an existing clone instead of a server-side mirror) and what happens without it (mirror-backed registration). It names the alternative for fetching ('use sync_repo for that, or simply read the project') and the update semantics for an already-registered project, leaving nothing to inference.

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