get_list_items

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

With no annotations, the description carries the burden of behavioral disclosure. It states that the tool returns items 'organized by section with their completion status,' which communicates the read-only nature and the return shape beyond what the schema provides. It does not cover edge cases like missing lists, but for a straightforward retrieval tool this is adequate.

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 tightly structured: a one-sentence summary, a short bulleted list of example queries, and a one-sentence return behavior note. Every part earns its place without redundancy or 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 read-only list-item retrieval tool with no output schema and no annotations, the description explains the core purpose, common phrasing, and return organization. It could mention behavior when both listName and listType are supplied or when the list is not found, but the schema and simple tool scope make the description reasonably complete.

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% and every parameter already has a clear description, including the enum for listType and the default for includeCompleted. The description's example queries add modest real-world context but no new semantic detail beyond what the schema already communicates.

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 opens with a specific verb+resource: 'Get items from a specific Skylight list,' which clearly identifies the operation and distinguishes it from sibling list management tools like get_lists. Example user questions further reinforce that this tool retrieves the contents of a list, not list metadata or aggregation.

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 'Use this to answer' section provides clear, concrete use cases such as 'What's on the grocery list?' and 'Show me my to-do list,' making it easy for an agent to know when to invoke the tool. However, it does not explicitly name alternatives or state when not to use it relative to sibling tools like create_list_item or get_lists.

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