Update a list item on a Skylight frame by changing its label, checking or unchecking it, or assigning it to a section. Use this to keep shared lists accurate with item details and completion status.
Update a list item on a Skylight frame.
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | ||
| itemId | Yes | ||
| listId | Yes | ||
| checked | No | true marks the item completed, false reopens it. | |
| frameId | No | ||
| section | No | Section name (null to clear). |
Changes observed during successful MCP inspections.
v1.0.1Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"v0.7.1Input schema / properties / section / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Input schema / properties / section / typeAdded value: +[
+ "string",
+ "null"
+]v0.4.6Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations indicate a mutating but non-destructive operation, and the description merely restates this by saying 'Update.' It does not explain whether fields are partially updated, whether optional fields reset existing values, how checked/section interact, or any side effects. No behavioral context beyond the annotations is provided.
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 description is a single concise sentence with no filler or repetition. It is front-loaded with the action and object, but it is so minimal that it sacrifices useful detail; still, from a pure conciseness standpoint, it is well-formed.
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 mutating tool with six parameters, no output schema, and low schema coverage, the description is far too thin. It does not clarify which fields can be updated, whether frameId is needed, what the request should look like, or what success/failure responses imply. An agent would need additional context to invoke this reliably.
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 description coverage is only 33%, with semantics provided only for 'checked' and 'section.' The tool description adds no parameter meaning, leaving label, frameId, itemId, and listId without explanatory context. The description fails to compensate for the low schema coverage.
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 identifies a clear verb ('Update') and resource ('a list item on a Skylight frame'), so an agent can grasp the core operation. It does not explicitly distinguish itself from closely related siblings like skylight_update_list or skylight_set_list_item_section, but the operation type is clear enough for basic selection.
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 offers no guidance on when to use this tool versus alternatives such as skylight_add_list_item, skylight_move_list_item, or skylight_set_list_item_section. There are no conditions, prerequisites, or exclusion notes, so an agent must infer usage solely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.