list_incidents

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

Annotations already cover readOnlyHint=true and destructiveHint=false. The description adds useful behavioral caveats not available in the annotations: empty pages can occur due to ACL, and the consumer should use next_offset/total when present. This is meaningful context beyond the structured annotation.

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 compact and front-loaded with the main purpose and immediately provides a concrete query example plus an ACL/pagination caveat. Each sentence contributes meaning without lengthy filler, though it packs quite a bit into two short blocks.

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?

The 4 parameters are optional, annotations declare a read-only/open-world tool, and an output schema exists. The description covers the essential query format, edge-case behavior around ACL filtering, and pagination hints. This is relatively complete for a tool definition, although the offset/limit parameters are still somewhat underspecified.

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 0%, so the description must compensate. It adds meaning for query by giving an encoded-query example and identifies fields and pagination as explicit components. However, the exact semantics of limit and offset, and how fields maps to parameter values, is only implied, so it does the job only partially.

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 says 'Lista incidentes' with ServiceNow encoded query, fields, and explicit pagination, which is a specific verb and resource. It clearly distinguishes from siblings like get_incident, create_incident, update_incident, and add_incident_comment because it is the only listing tool.

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?

There is no guidance on when to choose list_incidents over get_incident or the other sibling tools. The description provides operational details (query example, ACL empty-page behavior) but does not explain selection criteria or exclusion situations.

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