skylight_create_category

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

With no annotations, the description carries the full burden. It discloses that linked_to_profile and selected_for_chore_chart must be combined to create a full chore-chart member and explains the avatar workflow, but it does not state success results, failure modes (e.g., duplicate label), or side effects of linked_to_profile such as user creation.

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?

Two compact, front-loaded sentences. The first states the primary action, and the second delivers the two most important workflow caveats (flag combination and avatar sourcing) with no redundant 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 6-param create tool with no output schema and no annotations, the description covers purpose, flag semantics, and avatar flow, but leaves frameId's role unexplained and never states what the call returns or whether duplicate labels are rejected.

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 83%, so baseline is 3, and the description adds real value beyond it: it instructs agents to set linked_to_profile and selected_for_chore_chart together for a full member and tells them exactly where to source avatar_id. Only frameId remains unexplained in both schema and description.

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 and resource ('Create a category / family member on the frame') with location scoping. The wording clarifies that category and family member are the same entity, and the name contrasts clearly with sibling create/update/delete category tools.

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?

Names skylight_list_avatars as the source for avatar_id and skylight_set_member_avatar as the route for custom photos, giving concrete workflow guidance. It does not explicitly exclude this tool for updating existing members (skylight_update_category), but the create/update split is implied by naming.

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