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

Annotations only cover the safety profile (non-destructive, idempotent, closed-world). The description adds genuinely behavioral facts beyond them: mutual exclusion per module and per project, that refusals name the running job, and that a platform-update refusal is transient and retryable. It also clarifies the repo change is applied at the next redeploy rather than immediately.

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 operation, then constraints in priority order. The verbatim refusal strings are slightly verbose and could be paraphrased, but they are actionable for an agent parsing errors, so they mostly earn their place.

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 mutation tool with no output schema and annotations already covering safety, the description supplies the concurrency, retry, and timing details an agent needs. Remaining gaps are minor: whether the rename must be unique, and what happens to the module if the new repo fails to build.

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 value on the schema's biggest ambiguity: it states module_name and github_repo_url are interchangeable/optional ('or both'), implying at least one is needed alongside the required module_id. It does not, however, restate the URL format or name-conflict rules.

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+resource pair ('Rename a module, or point it at another GitHub repository') and clarifies the deploy timing consequence. This clearly separates it from siblings like rename_project, set_module_env, and set_module_resources.

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?

Explicitly says what to pass ('module_name, github_repo_url or both'), and states both blocking conditions with the exact recovery path: wait on the running job via get_job_status, or retry in a few minutes during a RationalBloks update. It names the alternative tool and the trigger condition.

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