sb_page_repair

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

Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds real value beyond these: the dry_run default of true (a safety mechanism aligning with non-destructive behavior), the draft-only mutation scope, and the re-publishing note for published pages. It is consistent with the annotations and enriches the behavioral contract.

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 dense sentences with no filler. The main action is front-loaded, and scope, draft handling, and dry_run safety are packed into ~40 words. Every sentence earns its 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 batch-capable mutation tool with no output schema, it covers the core operation, scope control, draft-only behavior, and dry_run safeguard. Minor gaps: site_id semantics and what the dry_run listing actually returns are not specified, but the operation is well understood without them.

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 0%, so the description must carry the parameter meanings. It covers dry_run (default true, lists what would change) and page_id (target one page, or omit for all pages), but site_id is entirely unmentioned. Two of three parameters are meaningfully explained, compensating partially but not fully for the missing schema documentation.

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?

The description states a specific verb (rename), resource (page root), and precise condition (root not 'ROOT', e.g., sppro_1 or rt_<hex> left by older seeds). It clearly distinguishes from siblings like sb_page_create, sb_publish, and sb_page_state, all of which handle different operations.

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 description gives clear context: it's for fixing legacy malformed page roots, with scope (one page vs every page via page_id) and a draft-only restriction with published pages listed for re-publishing. It doesn't explicitly name alternatives or state when NOT to use it, but the legacy-seed trigger and draft-handling make the use case well understood.

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