update_component

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

With no annotations, the description carries the full burden and does real work: it discloses partial-update semantics per field, that html/css/js are replaced wholesale (not merged), and that a revision is recorded. It omits permission/auth requirements and any effect on the public site, but the mutation behavior is well disclosed.

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 short sentences, front-loaded with the action, then the two most consequential semantics. Every sentence earns its place with no filler.

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 7-param mutation tool with no output schema and no annotations, the description covers the key update semantics. It does not address permissions, permalink/site-wide component implications, or rollback of the recorded revision, leaving minor gaps.

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 already 86%, so baseline is 3. The description adds genuine meaning beyond the schema by distinguishing scalar fields (partial merge) from html/css/js (wholesale replacement), which is a semantic distinction the schema itself does not state.

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 (update) and resource (component), clearly distinguishing it from get_component/create_component/delete_component by name. It does not explicitly differentiate from the parallel update_page sibling, but the resource is unambiguous.

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?

Usage context is implied rather than stated: patch semantics ('only the fields you pass are changed') tell the agent how to call it, but there is no guidance on when to choose update_component over update_page or create_component, and no prerequisites.

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