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

Annotations declare destructiveHint=true and readOnlyHint=false, but the description adds far richer detail: exactly what each method does ('DELETE permanently removes the record, POST creates one, PATCH/PUT overwrite fields'), OAuth handling, placeholder substitution, and a full error taxonomy (401/403/404/422/429). No contradiction with annotations; description goes well beyond the structured fields.

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?

Front-loaded with the core purpose and mutation warning, then efficiently covers conventions, return format, and error codes. Every sentence carries information; for a generic executor of this complexity the length is justified, though it edges toward dense and could be slightly tightened.

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?

With no output schema and 8 parameters, the description carries full burden and delivers: return format ('parsed JSON response together with pagination and rate-limit metadata'), failure payload semantics with HTTP status explanations, destructive consequences, and fallback behavior. Highly complete for a complex generic tool.

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 adds genuine extra semantics: explains the double-underscore-to-bracket rewrite (filters__status becomes filters[status]), how {placeholders} get substituted from path_params, and the company_id/project_id fallback to procore_set_config. These conventions are not in the schema and materially help correct invocation.

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 the specific verb+resource: 'Executes any Procore REST API call' with a clear scope ('the only tool here that reaches Procore'). Strongly distinguishes from siblings by noting it is the only data-mutating tool and that it reaches endpoints 'not exposed as a dedicated tool.'

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 directs the agent to 'resolve the exact method, path, and parameters with procore_get_endpoint_details first' and gives concrete when-to-use guidance: prefers a GET to verify the target id exists before destructive calls. Names the workflow position ('Step 4') and alternative tool, making selection unambiguous.

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

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

The annotations already declare readOnly, idempotent, and non-destructive. The description adds significant behavioral context beyond those hints: it makes no Procore request, needs no authentication, cannot fail with 401/403, costs no rate limit, and returns a JSON object. It also connects the returned values to the expected inputs of procore_discover_endpoints, providing useful workflow behavior.

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?

Every sentence carries distinct value: the product description, when to use, the alternative tool, the output contract, the no-network behavior, and the workflow position. The content is front-loaded with the core purpose and then narrows to operational details, without repetition or filler.

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 a zero-parameter tool with no output schema, the description covers the complete context an agent needs: what is returned, how the output is used downstream, that authentication is unnecessary, and which sibling tool to use instead. It fully satisfies the discover -> detail -> call workflow, leaving no ambiguity about its role.

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?

The input schema has zero parameters, so schema coverage is complete by default. The description confirms this with 'Takes no arguments', and adds clarity about the plain JSON object return, though it could have been slightly more explicit about this being an empty input contract. Otherwise, no parameter information is missing.

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: 'Lists Procore's API surface as a Category > Module tree with an endpoint count.' It clearly distinguishes itself as the first step of a discovery workflow and explicitly differentiates from procore_search_endpoints, which is an alternative for when the resource name is already known.

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 gives direct usage criteria: 'Start here when you do not yet know which part of Procore holds the data you need' and names the alternative when you do know the resource ('procore_search_endpoints gets you there in one step'). It also states it reads a bundled catalog, so it needs no authentication and costs no rate limit, which clarifies when to select it over network-calling tools.

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

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

Annotations already state readOnly, idempotent, and non-destructive, and the description adds key behavioral context: it reads a bundled catalog, makes no network request, requires no authentication, and has no rate-limit cost. It also discloses the full-catalog fallback when all arguments are omitted and the empty-array behavior for no matches, going well beyond the structured 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?

The description is slightly long but every sentence earns its place: it covers purpose, workflow placement, sibling alternatives, argument warnings, return format, error behavior, and cost implications. It is front-loaded with the main action and then provides structured detail without redundancy or padding.

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?

With no output schema, the description clearly states the return shape (JSON array of {operationId, summary, method, path}) and how to chain the result into procore_get_endpoint_details. It also documents the no-match empty-array behavior, the unbounded result risk, and the read-only/local nature, making the tool fully understandable for a four-optional-parameter, no-output-schema tool.

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%, so the baseline is 3, but the description adds meaningful parameter relationships not in the schema: module is ignored unless category is also given, all arguments are optional but at least one is recommended, and combining category with search narrows a large module. These extra constraints and usage hints improve parameter understanding beyond the field descriptions.

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 ('Lists') and a clear resource ('Procore endpoints inside one category or module'), with optional narrowing by summary substring or HTTP method. It explicitly distinguishes itself from siblings by directing users to procore_search_endpoints when they have a keyword but no category, and to pass operationIds to procore_get_endpoint_details.

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 gives explicit when-to-use guidance: use after procore_discover_categories, prefer procore_search_endpoints for keyword-only searches, and avoid calling with no arguments because it returns the entire ~3,100-endpoint catalog. It also explains filter behavior (empty array on no match) and that it reads the bundled catalog, so it is the right choice when avoiding API cost.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, but the description adds crucial behavioral context beyond that: it never returns token values or the client secret, it reads only local process state, and it does not send a Procore request. This fully covers the safety and privacy-relevant behavior that an agent needs.

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?

Every sentence carries distinct value: output scope, when to use, what is withheld, no-arg behavior, return format/side-effect, and with which sibling to change values. It is front-loaded with the core purpose and remains compact despite conveying substantial guidance.

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?

The description is complete for a zero-parameter, low-complexity read tool. It explains what is returned, what is not returned, how to use it in failure scenarios, and how to change the configuration via sibling procore_set_config. No output schema exists, but the summary of the JSON result is sufficient.

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?

There are zero parameters, and the description confirms 'Takes no arguments.' With 100% schema coverage and no params, the baseline is high, and the explicit no-arguments statement removes any ambiguity about input requirements.

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 the specific verb 'Reports this server's current state' and names the exact data it returns: OAuth token validity, default company_id, and active project_id. This clearly distinguishes it from siblings like procore_set_config (which changes values) and procore_api_call (which consumes them).

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 gives explicit guidance: 'Check this first when a call fails with 401 or 403, or to confirm which project subsequent calls will target before running a write.' It also names the related tool for mutation ('Pair with procore_set_config') and clarifies that it makes no Procore API request, so there is no confusion about side effects.

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

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.

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds critical context: it reads a bundled catalog with no network requests or rate-limit cost, and returns an empty array on no matches. This goes beyond annotations and clarifies operational behavior.

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 compact with every sentence adding value: purpose, usage, return format, edge case, and cost context. No redundancy or filler.

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 simple one-parameter tool with no output schema, the description fully covers behavior, return structure, alternatives, and caveats. Everything a caller needs to know is included.

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% with detailed parameter description, but the description adds a useful tip that 'single keywords match more broadly than phrases,' enriching semantic understanding beyond schema alone.

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 searches all endpoint summaries, tags, and paths for a term and returns ranked matches. It uses specific verbs and resources, and explicitly contrasts with procore_discover_categories for browsing vs searching.

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 provides explicit when-to-use guidance ('when you already know roughly what you want') and when-not-to (use procore_discover_categories for browsing). It also advises retrying with broader terms before concluding absence, giving actionable alternatives.

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

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

Adds substantial context beyond annotations: in-memory lifetime with process-lifetime scoping, no disk writes, loss on restart, idempotency of repeated sets, integer coercion semantics, that non-numeric values are reported rather than stored, and explicit assurance that nothing in Procore itself is modified. This goes well beyond what readOnlyHint=false communicates and prevents the agent from misjudging the side-effect profile. No contradiction found.

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 opening sentence front-loads the purpose, and while the description runs long (~170 words), each sentence provides distinct value covering usage, validation, persistence, idempotency, side effects, and return value. A capable editor could trim slightly, but there is no fat.

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?

With no output schema present, the description appropriately discloses the return value ('confirmation plus the full updated configuration'). Between annotations and text, the agent understands validation, side effects, scope, and return behavior completely. There are no material gaps.

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% with detailed per-parameter descriptions, establishing a baseline of 3. The description adds value by revealing coercion behavior, rejection semantics for invalid keys/values, and error-handling outcomes that the schema alone doesn't make explicit.

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?

Uses a specific verb+resource pair ('Sets the default company_id or project_id') and clearly distinguishes this tool by explicitly naming the sibling it feeds into ('procore_api_call') and the sibling used to confirm changes ('procore_get_config'). The scope and effect are unambiguous.

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 tells the agent when to use it ('to switch project context mid-session instead of restarting the server') and points to procore_get_config as a follow-up to confirm state. This gives clear decision context against named alternatives.

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