Get Full Endpoint Details

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe-read nature is covered. The description adds valuable behavior: that it reads a bundled catalog (no Procore request, no auth, no rate-limit cost), that an unrecognized operation id returns a not-found message rather than an error, and that it returns a not-found response. It does not contradict annotations. While it doesn't detail the exact response structure (no output schema exists), but the description mentions 'response shape' as part of the payload, and the lack of cost/auth details are beyond what annotations provide.

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 three sentences, each earning its place: function, workflow position, parameter source, behavior on error, and side-effect-free nature. No wasted words. It front-loads the primary purpose and key constraint (matching parameter names).

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?

Despite having no output schema, the description clearly outlines the return shape ('complete parameter schema ... plus the response shape'). It covers prerequisites, error behavior, side effects, and integration with sibling tools. Given the tool's simplicity (one param, read-only, no auth), this is 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% (1 param with description), but the description adds significant context beyond schema: it clarifies the parameter is the operationId from discovery/search tools, that it's case-sensitive and not a URL path. It also explains the consequence of an unrecognized value. This exceeds baseline 3, though it doesn't spell out exact format or validation rules beyond what's already in 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?

Description clearly states it returns the complete parameter schema for a Procore endpoint, specifying path, query, body fields, and response shape. It distinguishes from siblings by tying to operationId from discovery tools and positioning as 'Step 3' of the workflow, differentiating from api_call, discover, and search functions.

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?

Explicitly says 'Call this after discovery and before procore_api_call' and explains api_call needs exact parameter names. It also specifies the input ('operationId string that procore_discover_endpoints and procore_search_endpoints return') and how to handle non-matching IDs ('unrecognized operation_id comes back as a not-found message rather than an error'), providing both when and when-not to use it versus alternatives.

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