List purchase-requisitions

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

The description discloses useful behavioral details: returns at most 500 rows and sorts by newest change first. However, with all annotations set to false (readOnlyHint=false), there is no indication of safety or side effects. The description does not explicitly state that listing is read-only, which is a meaningful gap given the annotation suggests the tool might not be read-only. It also omits pagination semantics beyond the 500-row cap.

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?

Two sentences, no fluff. The essential information (what is returned, filters, row limit, ordering) is packed into a brief, front-loaded format. Every clause earns its place; nothing is redundant or missing. This is a model of efficiency.

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 list operation with two optional filters and no output schema, the description covers the key aspects: result fields, filtering options, row cap, and sort order. Minor gaps include the lack of an explicit statement about read-only behavior (given readOnlyHint=false) and the absence of clarification on combining filters. These are not critical for a list, but a tiny bit more detail would make it complete.

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% and each parameter already has a descriptive comment. The description only paraphrases the filtering capability ('Filter by category or by a word in the name') without adding nuance, such as whether filters combine with AND or OR, or how hyphenation applies to both. Since the schema carries the full semantic weight, the description adds marginal value, warranting the baseline score.

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 lists purchase-requisitions and enumerates the returned fields (category, version, step count, runs count). It specifies filtering by category or name, which distinguishes it from sibling tools like purchase-requisition_show (for a single item) and create/delete (mutations). The purpose is unmistakable and specific.

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 implies when to use it (whenever you need multiple purchase-requisitions with summary info) but does not explicitly contrast with alternatives like show or run_list. It lacks explicit 'when not to use' guidance, though the scope is clear enough for an agent to infer typical usage. The presence of a list-oriented sibling set helps, but the description itself offers no direct routing advice.

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