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

Beyond the annotations, the description discloses spec validation, idempotency-key handling, capped pagination behavior, the read-only server restriction, parameter placement rules, field projection, money/credit conventions, and API-key hygiene. Although the write-related language creates slight internal tension, it resolves explicitly to the read-only behavior declared by the 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 dense but front-loaded, starting with purpose and then covering behavior and parameter guidance. It is appropriately sized for a complex dispatcher, though it mixes protocol behavior, safety constraints, and data conventions into one compact paragraph.

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 10-parameter generic API dispatcher with no output schema, the description covers the essential invocation model, read-only behavior, pagination, and field reduction. It does not explain the return shape or error behavior, and it could more explicitly route the agent to hb_describe_operation before calling an unfamiliar operation.

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 the schema already documents each parameter. The description still adds useful cross-parameter context, including how path/query/body values map, dotted `fields` paths, and the convention that credits are units while money is integer pence with a currency.

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: 'Call any Hub API v2 operation by id.' It clearly distinguishes this generic dispatcher from sibling tools such as hb_search_operations and hb_describe_operation by making the operation id the central input.

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 gives clear operational constraints: the server is read-only, only GET operations run, and writes are refused. It also explains where to put path parameters, filters, JSON body, and how to use fields/all_pages, but it does not explicitly name sibling alternatives such as hb_describe_operation for inspecting an operation first.

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 and closed-world, so the safety profile is covered. The description adds genuinely new behavioural context: retries are part of the delivery explanation, and the payload is explicitly privacy-scrubbed (ids, statuses, dates, candidate_ref; never names, emails or health data), which tells an agent it can safely surface this output.

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 tight sentences, front-loaded with the verb and resource, then the return contents, then the privacy constraint and the 'knowledge only' qualifier. No 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?

No output schema exists, so the description must carry return-value information — and it does, naming all four return components plus the payload field categories. For a one-parameter read tool with rich annotations, nothing an agent needs is missing.

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 is a single required parameter at 100% schema coverage, with the schema itself supplying the example form 'occupational-health.request.submitted'. The description adds no further naming convention, wildcard or nesting rules, so it sits at the baseline for a fully documented 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?

Specific verb+resource ('Describe one webhook event') with an enumerated account of what the description returns: summary, retry behaviour, payload schema, sample payload. The singular 'one' implicitly separates it from the sibling hb_list_events, which enumerates many.

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 trailing 'Knowledge only.' signals this is static reference information rather than live data, which is useful, but the description never states when to reach for it versus hb_list_events or hb_describe_operation, nor any prerequisite such as obtaining the event_type first.

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 cover safety (readOnly, idempotent, non-destructive), and with no output schema the description does real work by disclosing that side effects (credits, health data, destructive, idempotency) and documented errors are returned. It doesn't state pagination, size limits, or behavior for invalid operation_ids, keeping it out of the top band.

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?

A single dense but well-ordered sentence that front-loads the return contents and closes with the actionable directive 'Read this before any write.' No filler, though the enumerated list is long enough to border on a run-on.

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 must explain what comes back, and it does so exhaustively: parameters, body schema with required fields and an example, required scope, side effects, errors, and a ready-to-use call. Nothing an agent needs before invoking it is missing.

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% and the single operation_id parameter already carries an example ('hub.candidates.list'); the description adds no further semantics about the identifier format or lookup behavior beyond referencing the example call. Baseline 3 applies when the schema does the heavy lifting.

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 a specific verb/resource ('Full detail of one operation') and enumerates exactly what it returns, which cleanly separates it from hb_search_operations (find operations) and hb_call_operation (execute one). An agent can pick this without opening the schema.

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?

'Read this before any write' gives a clear directive on when to invoke it and implicitly positions it as the precursor to hb_call_operation. It stops short of naming explicit alternatives or when-not-to-use conditions, so it's strong but not exhaustive.

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 readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so 'sends nothing' largely repeats that structured signal. The description does add value by stating the return payload shape (type and one-line summary), which no output schema provides. However, it says nothing about ordering, completeness guarantees, or what happens when filters match nothing.

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?

Three short sentences, front-loaded with what the tool returns, followed by the optional filters and the safety note. Every sentence adds information, and there is no 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?

For a zero-required-parameter, no-output-schema listing tool, the description covers the return shape, the filter behavior, and the read-only nature, which is enough for correct invocation. The main missing piece is disambiguation from hb_describe_event, which the description should include but currently leaves out.

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 both parameters are already documented, which sets the baseline at 3. The description repeats the portal example and adds the notion of matching against 'type or summary' for the text filter, which slightly enriches the schema wording but does not go beyond it.

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?

Specific verb (List) plus resource (webhook events Hub can send), with the scope quantified (59) and the return shape named (type + one-line summary). It is clear on its own, but it does not distinguish itself from the sibling hb_describe_event, which covers the same resource space.

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 sentence about optional filtering implies the browse-vs-filter workflow, and 'Knowledge only: sends nothing' clarifies that this is a discovery call. However, there is no explicit guidance on when to call this tool versus hb_describe_event, and no prerequisites or exclusions are stated.

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/closed-world, and the description reinforces with "sends nothing, needs no key" plus a concrete return format (snippet + resource URI) that annotations cannot convey. It doesn't state ranking behavior or what happens on zero matches, but the value-add over annotations is real.

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 sentences, front-loaded with the action and result, followed by scope and the knowledge-only constraint. No filler or restatement of the name.

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 supplies the return format and the follow-up resource URI, and it clarifies the closed-world knowledge-only nature. An agent has everything needed to decide to call it and to act on results.

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 an enum description for group and defaults/max for limit, so the schema already does the work. The description adds only the loose "by words" hint and example-style phrasing implied by the query schema, nothing beyond it.

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 a specific verb and resource (search bundled guides) and names the return shape (best matches, snippet, and the hb://guides/<name> resource). It also enumerates the covered content (Hub API v2 and developer portal guides), which separates it from the sibling hb_search_operations tool that indexes operations rather than prose guides.

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?

"Knowledge only: sends nothing, needs no key" clearly frames this as the read-only lookup path for conceptual questions, distinguishing it from the call/operation tools. It stops short of explicitly saying when not to use it (e.g. use hb_describe_operation for exact request schemas).

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, so the description does not have to explain safety. It adds real value beyond that: what fields come back (id, method, path, summary, scope, flags, callable-now) and the fact that per-operation flags include credits, health data and destructive markers. It does not discuss result cap behavior or pagination beyond what the schema says.

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 sentences, zero filler. Capability, return shape and the intended call sequence are all front-loaded in that order.

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?

There is no output schema, so the description compensates by enumerating the returned fields and the callable-now signal. Combined with a well-described 6-parameter schema and clear annotations, an agent has everything needed to call it and act on the results.

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 83%, so the schema already carries most parameter meaning and a 3 would be the baseline. The description still maps its searchable facets directly onto the parameters (query, toolset, method, scope), reinforcing how each narrows the search, which adds modest value over 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?

States a specific verb and resource ('Search the 189 Hub API v2 operations') plus the exact facets it searches over (text, toolset, method, scope). A reader immediately distinguishes it from hb_describe_operation and hb_call_operation, which the description also names.

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?

Gives an explicit workflow: 'Start here, then hb_describe_operation, then hb_call_operation,' which tells the agent the correct entry point and ordering. It stops short of exclusions (e.g. when to prefer hb_list_events or hb_search_guides), so it is strong but not fully exhaustive.

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, and the description adds meaningful context: it reports environment, base URL, key scopes, write enablement, toolsets, and rate limit. "Never reveals a key or token" is a useful safety disclosure beyond the 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 compact and front-loaded with the core question, followed by a precise list of reported fields. Every sentence earns its place, and the final "Call this first" instruction is clear and actionable.

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?

There is no output schema, so the description carries the burden of explaining return values, and it does so thoroughly. For a parameterless diagnostic tool, it provides enough detail for an agent to understand what will be returned and when to call it.

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 tool has zero parameters, so there are no parameter semantics to explain. The description appropriately avoids inventing inputs and focuses on behavior and returned information.

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 states a specific purpose: reporting caller identity and permissions via GET /auth/me. It distinguishes this diagnostic tool from the sibling operation, event, guide, and webhook tools by explaining exactly what status information it returns.

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?

"Call this first" gives explicit ordering guidance for using this tool before others. It does not discuss when not to use it, but for an identity/status tool with no parameters that scenario is less relevant.

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 cover safety (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantial behavior beyond them: the exact signing algorithm, the 300-second replay rejection window, the byte-for-byte raw-body requirement, the HB_WEBHOOK_SECRET env fallback, and a secret-handling caution. These are exactly the facts an agent needs to call it correctly and none are in the 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?

Five short sentences, front-loaded with the single most decision-relevant fact (local, no network), then the algorithm, then the mode switch. There is mild overlap between "300 seconds" and `tolerance_seconds`'s default, but it is justified because it also states the rejection behavior.

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 carries the return-value burden and only half covers it: it implies compute returns the signature string, but never says what verify returns (boolean, error, mismatch detail). Everything else an agent needs — inputs, algorithm, replay policy, secret source — is present.

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 the baseline is 3, but the description adds meaning the schema does not: that `signature` being omitted flips the tool into compute mode, that `secret` falls back to an environment variable, and that `body` must be passed byte-for-byte rather than parsed. Only `now_epoch_seconds` and `tolerance_seconds` are left purely to 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?

Opens with a specific verb pair and resource: "verify or compute a Hub webhook signature", and immediately distinguishes itself from every sibling by declaring "Pure local helper (no network)" — the siblings are all remote API tools. An agent can classify this tool without opening the schema.

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 gives the mode switch ("Omit `signature` to just compute it") and a situational recommendation ("prefer a sandbox secret if you pass it in chat"). It doesn't name a when-not-to-use case or an alternative tool, but none of the siblings overlap, so there is little left ambiguous.

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