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

Annotations only provide negative hints (readOnlyHint false, destructiveHint false), so the description carries the burden of behavioral disclosure. It adds auth requirements ('Needs your API key'), describes the side effect of creating a ticket with evidence attached, and details reply actions including resolve/reopen. It also specifies return shapes per action. It does not explicitly state non-idempotency of create, but given the richness of the description, this is a minor gap.

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 dense but well-structured: it front-loads the purpose ('Your support tickets'), then enumerates actions with parameters, follows with usage triggers and exclusions, and ends with return summaries and auth note. While it is a long sentence, every segment earns its place, and there is no redundancy. It could be slightly more concise, but the structure is logical and scannable.

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 tool with 9 parameters, no output schema, and only minimal annotations, the description covers all essential aspects: action semantics, per-action parameter usage, return structures (create/reply vs list vs get), auth requirement, and explicit exclusions. It even includes the contextual trigger 'doorway said to file it', making it nearly complete for correct invocation.

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 only 44%, and several parameters (subject, message, category, reopen, resolve) lack descriptions. The description fully compensates by mapping each parameter to its action context: 'create (subject, message, optional request_id of the failing call, optional category)', 'list (optional status)', and 'reply (reference, message, optional resolve/reopen)'. It also clarifies the meaning of request_id and reference explicitly, adding critical semantic value beyond the schema.

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 specifies the resource ('support tickets') and lists four concrete actions with parameter mappings, making the function's purpose unambiguous. It also explicitly distinguishes itself from sibling tools: 'Not for reading what an error code means (use explain_error first) and not for product ideas (use manage_feedback).' This level of specificity ensures an agent can select this tool correctly.

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 provides precise triggers for use: 'when a call was refused or failed and the doorway said to file it, or to follow up.' It also names alternatives and exclusions, e.g., 'Not for reading what an error code means (use explain_error first).' This gives the agent a solid decision rule and eliminates ambiguity.

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