Update Webhooks Hook (Deprecated)

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

Beyond the annotations, the description discloses deprecation schedule, patch semantics (omitted fields keep current values), required parent record existence, successful return value, and common error statuses. This provides rich behavioral context that annotations (readOnly=false, idempotent=true, destructive=false) do not cover.

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 information-dense yet well-organized, covering deprecation, scope, usage, id resolution, return value, errors, required params, and the endpoint in a compact paragraph. Each clause provides necessary context without redundancy.

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 single-parameter deprecated tool with no output schema, the description provides comprehensive context: what it does, when to use alternatives, how to prepare the id, expected success and failure responses, and API reference. The minor gap of not enumerating mutable fields is offset by the deprecation guidance to find newer versions.

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 schema has only one parameter (id), and the description adds meaning by instructing to resolve it with the list tool first and emphasizing that it must identify an existing parent record. However, the description mentions 'Send only the fields you intend to change' which implies additional mutable fields not defined in the schema (additionalProperties: false). This creates a slight inconsistency, but the description still offers valuable guidance 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?

The description clearly identifies the tool as updating a webhooks hook via PATCH, with the scope constraint ('within a company and/or project scope'). It also includes the endpoint and deprecation notice, making the action and resource unambiguous. This distinguishes it from siblings like update_company_webhooks_hook and update_project_webhooks_hook by labeling it as the deprecated generic version.

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 explicitly advises against using this tool when a newer version exists ('prefer a newer version... use procore_search_endpoints to find it'). It also provides prerequisites: resolving the id with the matching list tool, and partial update behavior ('Send only the fields you intend to change'). Error handling guidance (401, 403, 404) further clarifies when each failure occurs.

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