autotask_search_tickets

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

The description claims filters by 'priority' which is not a parameter in the schema, potentially misleading. It only mentions 'Max 500/page' for pagination but omits that page starts at 1 and other behavioral details like read-only nature (no annotations). It also understates the available filters (e.g., contactID, searchTerm, date ranges).

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 concise at two sentences, but it includes an inaccurate claim about a priority filter. The structure is clear, but the inaccuracy reduces its effectiveness.

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?

Given 11 parameters, no output schema, and no annotations, the description is incomplete. It fails to mention many filter options and pagination details (minimum page). The mention of get_ticket_details is a positive, but overall the description does not sufficiently equip an agent to use this tool correctly.

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 91%, so the schema already documents parameters well. However, the description adds confusion by mentioning 'priority' which does not exist in the schema, and it does not clarify any parameters beyond what is in the schema. This active misdirection hurts rather than helps.

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 clearly states the tool searches tickets by key criteria (company, queue, status, priority) and explicitly distinguishes it from autotask_get_ticket_details for full data. The verb 'search' combined with the target resource 'tickets' is specific and 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?

The description tells when to use this tool (searching filters) and explicitly advises using autotask_get_ticket_details for full ticket data, which is a helpful alternative. It does not provide negative usage guidance (e.g., when not to use), but the context is clear enough.

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