List search options

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds that it returns field IDs, names, and types, but since an output schema exists, this is mostly redundant rather than new behavioral context.

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?

Three short sentences, front-loaded with the core purpose and then the usage tie-in. The return-value sentence is somewhat redundant given the output schema, but no sentence is wasted in a harmful way.

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 simple, single-parameter read-only tool with full schema coverage, complete annotations, and an output schema, this description is sufficient. It says what it lists, when it is useful, and what it returns, leaving nothing critical for an agent to infer.

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 100% for the single 'itemtype' parameter, so the schema already explains the parameter and gives examples. The description only echoes that the tool works 'for an itemtype' without adding syntax or format details 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?

States a specific verb and resource: 'List available search fields for an itemtype.' It also names the sibling it supports ('glpi_search'), so an agent can distinguish it from other list tools without opening the schema.

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?

Gives clear context: 'Critical for building search criteria with glpi_search.' This tells the agent when to use it and which sibling it pairs with, but it does not state explicit exclusions or when another tool would be preferable.

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