Reqbeat Hiring Signals

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

Despite annotations already declaring idempotentHint and destructiveHint, the description adds substantial non-obvious behavior: the error is identical whether an id belongs to someone else or does not exist, cancelling frees a slot in a free key's watch limit, the call is never billed, and a blank key returns a signup link. These are real operational disclosures that annotations cannot convey, and nothing contradicts them.

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 definition is dense but nearly every clause carries useful information (idempotency, error semantics, billing, auth). The opening clause is awkwardly worded, and the examples and constraints are somewhat packed together, but the tool-relevant facts are front-loaded.

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 response shape ({id, canceled}), the idempotency guarantee, error behavior, billing and quota effects, and the auth requirement. An agent has everything it needs to invoke this correctly for a mutation 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 50% (watch_id has no schema description), so the description must compensate, and it does: it specifies that watch_id comes from watch_company or list_watches and that foreign/nonexistent ids produce the same error. It also references the key requirement, complementing the schema's deprecation note for plane_api_key.

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 identifies a specific verb and resource (cancelling a watch) and even shows the input/output transformation ({watch_id: 42} -> {id: 42, canceled: true}). It implicitly distinguishes itself from siblings by naming watch_company as the id source and list_watches as the way to enumerate ids, though the leading phrase 'WHEN a watch should stop firing' is slightly elliptical rather than a clean verb statement.

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 context for when this applies (a watch should stop firing) and explains how to obtain the required id from watch_company or list_watches. It stops short of explicit when-not guidance or naming a sibling it replaces, but the surrounding conditions are 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?

Annotations already cover safety (readOnly, idempotent, non-destructive, open-world), yet the description adds substantial behavioral context: exact-match domain semantics with a worked example, up-to-5 name candidates with match_confidence thresholds, the returned field set, no-hiring-signal warning, empty-list-instead-of-error contract, the never-billed note, and the signup-link fallback when no key is present. None of this is 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?

Front-loaded with the WHEN trigger, then ordered by domain semantics, name semantics, return shape, and edge cases. Every sentence carries distinct, actionable information (exclusivity rule, example, confidence values, error/empty behaviors) with 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?

With no output schema, the description fully specifies the return shape (`company_id`, `company_name`, `company_domain`, `country_code`, `coverage_status`), the empty-result contract, the no-key fallback, and the error condition. An agent has everything needed to invoke and interpret it correctly.

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 only 33% (just the deprecated `plane_api_key`), so the description carries the load and does so: it explains the exactly-one-of `domain`/`name` rule, that `domain` accepts a bare host or full URL and matches exactly (with an example), and that `name` returns up to five ranked candidates with confidence scoring.

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 ('Find company by domain or name') and immediately distinguishes itself from the siblings that consume its output, naming the `company_id`-dependent tools (`is_hiring`, `get_open_reqs`, `hiring_pulse`, `pre_action_brief`, `watch_company`). It also explicitly disclaims the hiring-signal role and routes to `is_hiring`, so the agent can separate it from every nearby tool without opening a 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?

Opens with an explicit trigger condition ('WHEN you hold a company's website or name but not the `company_id`') and states the bad call conditions ('both or neither is an error naming that rule'). It names the alternative for hiring data (`is_hiring`), giving both when-to-use and when-not-to-use guidance.

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 signal readOnly/idempotent/openWorld, and the description goes well beyond them: billing is per row returned and an empty page bills nothing, unknown criteria fields hard-error instead of being silently dropped, agencies and expired postings are excluded by default, pagination uses `cursor` from the prior `next_cursor`, and a missing key yields a signup link. That is exactly the behavioral context an agent needs before calling.

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-loads the WHEN clause and the one-call value proposition, then layers in criteria semantics, output shape, billing/auth, and the sibling alternative. Dense but every sentence carries information; the inline field enumerations are the only mildly heavy part.

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 correctly describes the returned rows (company name, posting URL, seniority, skills, declared/estimated pay the salary params bracket). Combined with billing, auth, and pagination notes it is close to complete, though a couple of secondary parameters remain undocumented.

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?

With schema coverage at only 10%, the description does the heavy lifting: it defines the three criteria groups (company/req/event) with their fields, the AND-across-fields / OR-within-one semantics, shows a concrete example, and explains `cursor`, `limit`, and how `salary_min_usd`/`salary_max_usd` bracket pay. It leaves `since`, `live_only`, `idempotency_key`, and `exclude_agencies` (only implied by 'excluded by default') unexplained, so a few gaps remain.

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 ('find live roles matching an ICP') and sharpens it with the operational outcome: matching open roles as actionable rows in ONE call rather than a search followed by per-company lookups. It also differentiates from sibling `who_is_hiring_for` (first look without a key), so an agent can route without opening either 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?

Opens with an explicit WHEN clause ('an agent already knows its ideal customer profile') and names the alternative for the opposite case ('For a first look at who is hiring before you have a key, use `who_is_hiring_for`'). It also states the precondition that an API key is required and what happens without one.

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?

Beyond the annotations (readOnly/openWorld/idempotent/non-destructive), the description discloses metering and cost behavior ('an empty page bills nothing and one `change` unit is metered per event returned'), a free-tier freshness floor, and the bounded-`limit` constraint that forces cursor pagination. These are operational traits the annotations cannot express.

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 disambiguating 'change feed, not a search' clause, then sequencing cursor semantics, cost, filtering, pagination, and the sibling relationship. Every sentence earns its place, though the backtick-dense phrasing is slightly packed for a single 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?

With no output schema, the description still names the key return fields (`next_cursor`, the event stream) and covers billing, freshness, ordering, and pagination. The remaining gaps are the shape of the event payload and the role of `idempotency_key` on a read-only 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 only 17%, so the description carries the load and does so for most parameters: `since` semantics (strictly greater-than, ascending order), `limit` being bounded and not to be raised, and the two filter params (`company_id`, one exact `event_type`). It leaves `idempotency_key` and the deprecated `plane_api_key` (covered in-schema) unaddressed, so it is strong but not exhaustive.

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 — a ledger-style change feed keyed on `event_seq > since`, ascending, returned with `next_cursor` — and explicitly frames it as 'not a search', which separates it from the search_* siblings. It also names `watch_company` as the push-based twin. An agent can distinguish this from every sibling without opening a 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?

Gives explicit when-to-use and when-not-to-use guidance: replay with `next_cursor` instead of polling or re-searching, page with the cursor rather than raising `limit`, filter by `company_id` or a single exact `event_type`, and use `watch_company` when push/webhook is wanted. Alternatives and the conditions selecting them are spelled out.

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 the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: deduping across boards, LinkedIn exclusion, freshness flooring, the distinction between first_seen and source_posted_at, and the fact that an invalid `function` returns an explicit error listing valid names rather than an empty result. That error-vs-empty-result contract is exactly the kind of non-obvious behavior 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?

The purpose is front-loaded and every sentence carries real information, but the prose is dense and hops between return-field semantics, error behavior, and limit bounds without clear structure, making it harder to scan than it needs to be.

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 usefully documents the meaning of returned fields (`boards`, `first_seen`, `source_posted_at`), which is the right call for a read-only list tool. It stops short of describing result shape or pagination beyond the bounded `limit`.

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 only 17%, so the description must carry the load. It does well for `function` (name or id, plus rejection semantics) and `limit` (oversized pages are rejected, not truncated), but says nothing about `country`, `company_id`, or `idempotency_key`, leaving half the parameters undocumented anywhere.

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 concrete verb+resource+scope: the company's current active reqs, deduped across boards and LinkedIn-excluded. An agent can tell what it returns, though it never contrasts itself with adjacent siblings like find_qualified_reqs or who_is_hiring_for, so sibling differentiation is only implicit.

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 explains what the data means but never says when to choose this tool over find_qualified_reqs, who_is_hiring_for, or search_jobs. No prerequisites, no exclusions, no alternative routing are given, so selection is left entirely to inference.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: LinkedIn-excluded scope, freshness floor, error-not-empty-success semantics, and the fact that failed lookups are not billed. That billing and error-shape disclosure is exactly the kind of context annotations cannot express.

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-loads the core purpose before scope and edge cases, and each sentence carries information. The em-dash-heavy middle clause is slightly dense, but 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?

With no output schema, the description carries the burden and does name the extra returned fields (`raw_title`, `boards`) plus the failure mode. It stops short of describing the overall response shape or the deprecated-header migration details, so it is strong but not fully 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 description coverage is only 25% (only the deprecated `plane_api_key` is documented), so the description must compensate. It usefully explains that `company_id`/`req_key` are the pair carried on `search_jobs` rows, but says nothing about `idempotency_key` or the type/format of `req_key`, leaving half the parameters unexplained.

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 ('one open role's detail') and the exact addressing scheme (`company_id` + `req_key`). It explicitly distinguishes itself from siblings `search_jobs` and `get_open_reqs`, so an agent can route without opening any 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?

Gives an explicit when-to-use rule: call this when you already hold an identifier for a role, rather than 're-pulling the whole company with get_open_reqs'. It also names a fallback behavior (no key -> signup link), leaving nothing to inference.

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?

Goes well beyond the readOnly/idempotent annotations: it discloses the crawling-state edge case (`{job_id, status:"crawling"}` and the warning not to read it as 'not hiring') and that freshness is governed by `max_age`. Doesn't discuss rate limits or auth, so not a 5.

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-loads the output contents, then usage, then the edge-case warning, then alternatives. Dense but every clause carries meaning; slightly long, but no wasted sentences.

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 no-output-schema, read-only tool, it fully describes the returned fields and the crawling fallback, which is the critical gap an agent would hit. Remaining unknowns (auth, pagination) are minor for a single-company pulse.

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 only 25%, so the description must compensate. It explains `max_age` semantics (freshness in seconds) which the bare schema doesn't, and clarifies `momentum` is a flow (postings per week) not a stock. `idempotency_key` and `plane_api_key` are left to the schema, keeping this short of a 5.

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: it enumerates exactly what one number set contains (count of reqs, `velocity` ratio, `direction`, surge flag, `momentum`) for a single company. An agent can tell precisely what comes back and how it differs from siblings like `is_hiring`.

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?

Explicit usage: 'rank or score a company you already hold a `company_id` for'. It names alternatives with conditions -- `pre_action_brief` for the whole picture, `is_hiring` for a cheap yes/no -- so routing is 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?

Beyond the readOnly/idempotent annotations, it discloses scope rules (LinkedIn-excluded, freshness-floored), the semantic meaning of coverage_status values, and the empty-string API key fallback returning a signup link instead of an auth error — real behavioral context annotations cannot carry.

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?

Dense and front-loaded — the WHEN clause leads, followed by scope, parameter guidance, examples, and the sibling pointer. Every sentence earns its place, though the packed parentheticals and dual examples make it longer than strictly necessary.

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, yet the description conveys return semantics via worked examples (is_hiring true with open_req_count 7 and coverage_status 'ats_direct_hit'; false with 'no_ats_signal'). An agent has everything needed to call and interpret 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?

Schema coverage is only 33%, so the description must compensate: it does so for company_id (integer id from an earlier result, not a name or domain, with a concrete example) and plane_api_key (empty string triggers signup link). idempotency_key is left unexplained in both schema and description.

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 precise intent — qualify whether a held company is hiring — and names itself as the 'cheap gate before spending a richer call.' It explicitly distinguishes from the sibling who_is_hiring_for, so the agent can route without opening schemas.

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 trigger ('WHEN an agent already holds a company'), contrasts with the discovery sibling ('To find companies in the first place, use who_is_hiring_for'), and adds both the no-key workaround and a warning not to treat 'no_ats_signal' as a negative. When/when-not/alternatives are all present.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavior: newest-first ordering, cancelled-watch exclusion, heartbeat fields (last_fired_at, fires_last_7d, rate_limited, status) and the 'never billed' cost note. It also flags the auth requirement ('Needs your key: a blank one returns a signup link').

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 WHEN clause and dense but purposeful. The inline JSON shape earns its place given no output schema exists. Slightly long, but every sentence carries information an agent needs.

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, so the description responsibly supplies the return shape (watches array with id, company_id, event_types, webhook_endpoint_id, status) and heartbeat semantics. Combined with the auth note, an agent has everything needed to call and interpret 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?

Single parameter at 100% schema coverage, where the schema already documents the deprecated plane_api_key. The description adds auth context beyond the schema ('Needs your key', blank key returns signup link), which is meaningful for invocation even though it is not a per-parameter spec.

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 ('List active watches') and immediately distinguishes scope: live watches, newest first, cancelled excluded. Distinguishes from `cancel_watch` and `watch_company` by clarifying what it returns and how its ids feed into the sibling.

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?

Explicit WHEN clause: 'before adding a watch, or to find the `id` `cancel_watch` takes.' Names the alternative sibling and the condition that selects this tool, leaving nothing to inference.

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/openWorld, so the bar is lower, yet the description still adds real behavior: it is a bounded single round-trip replacing five calls, each section is capped to keep payloads compact, `max_age` is honored in seconds, and a company with no ATS/board data returns a `{job_id, status: "crawling"}` sentinel. Auth expectations and the deprecated key path are left to the schema, keeping this short of a 5.

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 payload inventory, then the usage trigger, then the edge-case return and the cheaper alternative. The long enumeration sentence is dense but each listed section is substantively distinct; not a wasted sentence, though the opening list runs long.

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-shape burden and does so for the notable non-happy path (`{job_id, status: "crawling"}`) plus the section-level composition of the success payload. Remaining gap is the undocumented `idempotency_key` and no note on how large the capped payload may be.

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 only 25% (just the deprecated `plane_api_key`), so the description must compensate. It does explain `max_age` semantics (seconds) and contextualizes `company_id` as an id the caller already holds, but `idempotency_key` is never addressed, leaving one parameter undocumented in both places.

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 ('pre-action brief for one company') and enumerates the exact payload sections (hiring pulse, deduped open reqs, first-hire events, reposted reqs, ATS migrations). It explicitly differentiates itself from the sibling `hiring_pulse`, so an agent can select between them without opening another 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?

Gives a concrete trigger ('right before writing outreach or a qualification note'), a precondition ('a company_id you already hold'), and an explicit alternative ('If you only need the velocity number, `hiring_pulse` is cheaper'). When-to-use and the competing option are both spelled out.

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 the safety profile (idempotentHint=true, destructiveHint=false, openWorldHint=true), but the description adds materially more: the idempotency is explained concretely (same `url` returns the same id, retries never create duplicates), the `secret` lifecycle is disclosed (generated and returned exactly once, never retrievable again), and the `X-Reqbeat-Signature` header is named. The free-vs-billed note is extra operational context the annotations cannot express.

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 purpose and the 'call this first' ordering are front-loaded, which is exactly right. The second sentence, however, chains three distinct concerns (idempotency, secret lifecycle, billing) into one long dash- and parenthesis-heavy clause, which slightly hurts scannability even though every clause is informative.

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 must and does describe returns (`webhook_endpoint_id`, the one-time `secret`). Combined with the ordering rule, idempotency guarantee, and signature header, an agent has everything needed to call this correctly on the first attempt.

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?

With only 33% schema description coverage, the description carries most of the load: `url` is framed as a delivery target and `secret` is explained as optional, its verification role stated, and its one-time return behavior described. The only gap is `plane_api_key`, which the description ignores entirely, though the schema itself flags it as deprecated in favor of the header.

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 verb and resource ('Register the delivery target a watch fires to') and immediately names the artifact produced (`webhook_endpoint_id`). It clearly distinguishes itself from the sibling `watch_company`, which is the consumer of that id rather than a competitor for the same action.

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 an explicit precondition and ordering rule: 'call this first if you do not already hold one.' It also explains the relationship to the follow-up tool and even the billing consequence of the subsequent `watch_company` call, so an agent knows both when and why to reach for it.

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 the description still adds substantial behavioral detail beyond them: LinkedIn exclusion, freshness flooring, that `since` filters first_seen rather than the employer's posting date, source_posted_at null semantics, opaque keyset pagination, oversized-limit rejection rather than truncation, and the signup-link response when no key is present.

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?

Long but front-loaded: the core purpose and scoping clause lead, followed by parameter-specific behavior. Nearly every sentence carries operational information, though the prose is dense and slightly hard to scan given the many parenthetical asides.

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 12-parameter tool with no output schema and 8% schema coverage, the description is close to sufficient, covering filtering, exclusion, sorting, pagination, and error behavior. It is not fully complete because exclude_agencies, idempotency_key, and source_type are undocumented anywhere.

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 only 8%, so the description must carry the load, and it does for most parameters (q, geo, since, function, cursor, limit, sort, exclude_employer_types), including non-obvious ones like exclude_employer_types keeping unclassified rows unless 'unknown' is listed. Gaps remain: exclude_agencies and idempotency_key are never addressed, and source_type is left to its enum alone, which prevents a 5.

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 with unusual precision: 'Flat, role-granular job search' over 'individual open roles across companies matching function/geo/since, one row per logical req (each with its own company_id + req_key)'. It explicitly distinguishes itself from the sibling who_is_hiring_for as the 'company-granular reverse view', so an agent can route between them without opening schemas.

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?

Explicit routing guidance: use who_is_hiring_for for the company-granular reverse view, and pass `q` (plain language) or `function` depending on intent, with the failure mode ('anything else, like engineering, is rejected with an explicit error'). It also covers sort defaults, cursor paging versus raising limit, and the no-key fallback, which is exactly the when/when-not guidance expected.

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?

Rich disclosure well beyond the annotations: meters one watch unit, refuses unknown event types and creates nothing to avoid silent billing, enforces a free-key watch quota, and returns a 402 mirroring the REST route. Consistent with readOnlyHint=false and non-idempotent semantics.

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-loads the core action, then layers event semantics and error/quota behavior in three tight paragraphs. Dense but each sentence carries operational value; only the event glosses push length slightly.

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, but the description covers billing, validation failure, and quota/error behavior thoroughly. Minor gaps remain around success return shape and idempotency_key semantics, which an agent might want for a mutating call.

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?

With only 20% schema coverage the description must compensate, and it does for the two most important params: webhook_endpoint_id ownership constraint and full definitions of each event_types enum value (opened/reobserved/reposted/closed) not present in the schema. company_id and idempotency_key remain unexplained.

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: 'Subscribe to a company's hiring events on a registered webhook.' An agent can immediately distinguish it from siblings like cancel_watch, list_watches, and register_webhook.

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 a prerequisite (webhook_endpoint_id must belong to the same customer as the authenticated key) and hints at the lifecycle by noting cancelling returns the slot, but never states explicit when-to-use/when-not conditions versus alternatives such as pre_action_brief or register_webhook. Usage is implied rather than spelled out.

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 the safe read-only/idempotent profile, yet the description adds genuinely non-obvious behavior: per-company billing (~0.10 USD each, empty result free), keyset pagination, dedupe by company, unresolvable geo as a hard error rather than a partial page, and the no-key signup-link fallback. Those are things annotations cannot express, so this is well above the annotation bar.

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 WHEN clause and dense with concrete examples (q='backend engineer', geo='Atlantis') rather than filler. It is long and packed, but nearly every clause carries a distinct behavioral fact.

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 9-parameter, zero-required tool with no output schema and 11% schema coverage, the description explains the core search and return shape ('companies each with its pulse and matched reqs') but stops short of source_type, exclude_agencies and idempotency_key, leaving several knobs defined only by their type.

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?

With schema coverage at 11%, the description carries the burden and does so for the key inputs: q is free text against posting title (not an id) with inflection matching, geo is resolved to a stored country, limit is bounded so cursor is the pagination path. It leaves source_type, exclude_agencies and idempotency_key entirely undocumented, so it is not fully compensating.

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 precise verb+resource+scope: reverse 'who's-hiring-for' search returning companies with active reqs matching q/geo/since, deduped by company. It explicitly positions itself as the sourcing step and names the sibling it is not (is_hiring) for the yes/no case.

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?

Opens with WHEN to use it (sourcing before you know which companies exist) and closes by routing the 'already holding a company_id, need yes/no' case to is_hiring. Alternative and exclusion are both explicit.

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?

Goes well beyond the annotations: each call appends exactly one record, records are visible only to the caller's account, nothing is overwritten (so later stages must be reported as new outcomes), the operation is never billed, and an API key is required with a blank key yielding a signup link. This is consistent with destructiveHint=false and idempotentHint=false, and adds real operational context.

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 WHEN trigger, then arguments, then a worked example, then behavioral caveats — a logical order with no filler sentences. It is a dense single block rather than cleanly separated, which costs a point on structure but not on content.

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 shape ({"id": 87}), the authentication requirement and failure behavior, and the append-only semantics. An agent has everything needed to call and interpret this tool correctly.

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 only 20%, so the description must carry the load and does: it explains company_id, characterizes outcome as a short self-chosen label (e.g. "meeting_booked"), describes observed_at as the time the event happened, and clarifies that req_key is the optional role that prompted the outreach. A concrete JSON example pins down the expected shapes.

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 precise trigger and verb+resource: 'WHEN a company you reached through a signal converts ... report it back', and the title/name align with it. It is unmistakably the single write/reporting tool among read-only siblings like find_company, get_open_reqs and who_is_hiring_for.

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 clearly states the condition that should trigger a call (a reply, meeting, or closed deal on a company reached via a signal) and tells the agent to file a later stage as a new outcome rather than updating. It does not name alternatives, but no sibling tool performs a comparable write, so the omission is minor.

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