List Generic Tool Items

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

Goes well beyond the annotations by disclosing return format ('Returns a JSON array'), pagination behavior ('page and per_page control pagination and the response reports how many pages remain'), error handling ('Failures come back as an error payload carrying the HTTP status — commonly 401...403...404'), and the default for project_id. It also reinforces the read-only nature in prose. No contradiction with annotations.

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?

Although long, the description is information-dense and well-structured: purpose, tutorial link, usage, default behavior, pagination, read-only status, error codes, required parameters, API location, and endpoint. Every sentence adds a distinct piece of useful information, and the most important facts are front-loaded.

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 the tool's complexity (19 parameters, no output schema, annotations present), the description covers essential context: return format, pagination, error semantics, prerequisites, default behavior, and the full API endpoint. The only minor gap is the internal structure of each item, but that is not expected without an output schema, and the 'extended' view enum hints at richer detail through parameters.

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% for all 19 parameters, giving a baseline of 3. The description adds meaningful semantics that the schema lacks: project_id defaults to the value set by procore_set_config, generic_tool_id must identify an existing parent record, and page/per_page control pagination with pages remaining. These extras justify a score above baseline, though the schema still handles the bulk of parameter details.

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 opens with a specific verb and resource: 'Returns a list of all Generic Tool Items in the specified Project and Generic Tool.' It clearly distinguishes itself from sibling tools like list_generic_tools (which lists tools, not items) by naming the exact resource and scope, and even provides a use case: 'discover generic tool items or to look up the id of one before calling a tool that needs it.'

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?

Provides explicit when-to-use guidance: 'Use this to discover generic tool items or to look up the id of one before calling a tool that needs it.' It also names a prerequisite alternative: 'generic_tool_id must identify an existing parent record — resolve it with the matching list tool first.' This points the agent to call list_generic_tools first, which is a clear alternative and usage boundary.

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