Start a local webhook receiver to capture Oracle HCM notifications and verify incoming requests with HMAC-SHA256 signatures when a secret is provided.
Start localhost webhook receiver. When ORACLE_HCM_WEBHOOK_SECRET (or secret arg) is set, requires X-HCM-Signature HMAC-SHA256.
| Name | Required | Description | Default |
|---|---|---|---|
| port | No | ||
| secret | No | Override env secret for this receiver |
Changes observed during successful MCP inspections.
v0.4.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only include readOnlyHint=false, which is weak and does not indicate side effects. The description adds that the tool requires HMAC-SHA256 signature verification when a secret is set, which is helpful. However, it does not disclose other behavioral details such as whether it opens a persistent server, how it interacts with ongoing processes, or any cleanup requirements. Given the low annotation coverage, the description carries more burden but still falls short.
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 short sentences with no unnecessary words. The core functionality is stated upfront, followed by the security condition. It is highly concise and well-structured.
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 covers the essential purpose and security requirement, which is likely sufficient for an agent to call the tool. However, it lacks details on return values (no output schema), error handling, what happens after starting the receiver, and how the agent might interact with it after startup. Given the simplicity and that no output schema exists, a bit more detail on expected behavior would improve completeness.
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 50%, with one parameter (secret) documented. The description explicitly mentions the 'secret' parameter and explains its role, which adds value beyond the schema. The 'port' parameter is not described in schema or description, but it is straightforward. The description adequately clarifies the secret parameter's purpose, aligning with the 50% coverage baseline.
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 starts a localhost webhook receiver, which is a specific action and resource. It also mentions the authentication requirement when a secret is set, adding useful context. However, it does not explicitly differentiate from sibling tools like hcm_list_webhook_events, but the verb and resource are specific enough.
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 this tool is used to set up a local webhook receiver for testing or receiving webhooks. It does not explicitly state when to use it versus alternatives, though the sibling list includes webhook-related tools but none with a 'start' action. The absence of explicit context for when to use it makes it less clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.