Search items

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

Annotations already establish this as a safe, idempotent read, so the bar is lower, and the description clears it comfortably. It discloses non-obvious return behavior: rows keyed by localized search-option names, coded columns carrying both a label and a '<name> (id)' code key, and the raw-by-ID shape when named_columns=false.

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?

Dense but well front-loaded: the core purpose leads, followed by criterion shape, return-shape quirks, and the discovery pointer. Every sentence carries information, though the run-on criteria/return clauses could be split for faster scanning.

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 9-parameter tool with an output schema, the description covers what the output schema needn't: the localized-key and coded-column conventions, the named_columns toggle, and where to find valid option IDs. Nothing an agent needs to invoke it correctly is missing.

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%, so baseline is 3, but the description exceeds that by enumerating the searchtype values (contains | equals | notequals | lessthan | morethan | under), the link values, and the first-criterion omission rule, none of which appear in the schema. It also clarifies named_columns semantics beyond the schema's wording.

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 ('Search GLPI items with criteria') and enumerates the itemtypes it covers, so the agent knows it is a generic cross-type search. It does not, however, distinguish itself from the many typed siblings such as glpi_list_tickets or glpi_count_items, leaving the choice between generic search and dedicated list tools to inference.

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?

It gives clear operational context (each criterion's shape, link semantics, first-criterion omission rule) and explicitly routes the agent to glpi_list_search_options for discovering option IDs. It stops short of stating when to prefer this tool over the typed list siblings or when not to use it.

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